| 1 | ." $Header: ch2.n 1.7 83/07/30 14:42:38 layer Exp $ |
| 2 | .Lc Data\ Structure\ Access 2 |
| 3 | .pp |
| 4 | The following functions allow one to create and manipulate the various types |
| 5 | of lisp data structures. |
| 6 | Refer to \(sc1.2 for details of the data structures known to |
| 7 | .Fr . |
| 8 | .sh 2 Lists \n(ch 1 |
| 9 | .pp |
| 10 | The following functions exist for the creation and manipulating of lists. |
| 11 | Lists are composed of a linked list of objects called |
| 12 | either 'list cells', 'cons cells' or 'dtpr cells'. |
| 13 | Lists are normally terminated with the special symbol |
| 14 | .b nil . |
| 15 | .b nil |
| 16 | is both a symbol and a representation for the empty list (). |
| 17 | .sh 3 list\ creation |
| 18 | .Lf cons "'g_arg1 'g_arg2" |
| 19 | .Re |
| 20 | a new list cell whose car is g_arg1 and whose cdr is g_arg2. |
| 21 | .Lf xcons "'g_arg1 'g_arg2" |
| 22 | .Eq |
| 23 | \fI(cons 'g_arg2 'g_arg1)\fP |
| 24 | .Lf ncons "'g_arg" |
| 25 | .Eq |
| 26 | \fI(cons 'g_arg nil)\fP |
| 27 | .Lf list "['g_arg1 ... ]" |
| 28 | .Re |
| 29 | a list whose elements are the g_arg\fIi\fP. |
| 30 | .Lf append "'l_arg1 'l_arg2" |
| 31 | .Re |
| 32 | a list containing the elements of l_arg1 followed by l_arg2. |
| 33 | .No |
| 34 | To generate the result, the top level list cells of l_arg1 are duplicated |
| 35 | and the cdr of the last list cell is set to point to l_arg2. |
| 36 | Thus this is an expensive operation if l_arg1 is large. |
| 37 | See the descriptions of |
| 38 | .i nconc |
| 39 | and |
| 40 | .i tconc |
| 41 | for cheaper ways of doing the |
| 42 | .i append |
| 43 | if the list l_arg1 can be altered. |
| 44 | .Lf append1 "'l_arg1 'g_arg2" |
| 45 | .Re |
| 46 | a list like l_arg1 with g_arg2 as the last element. |
| 47 | .No |
| 48 | this is equivalent to (append 'l_arg1 (list 'g_arg2)). |
| 49 | .Eb |
| 50 | ; A common mistake is using append to add one element to the end of a list |
| 51 | \-> \fI(append '(a b c d) 'e)\fP |
| 52 | (a b c d . e) |
| 53 | ; The user intended to say: |
| 54 | \-> \fI(append '(a b c d) '(e)) |
| 55 | (a b c d e) |
| 56 | ; better is append1 |
| 57 | \-> \fI(append1 '(a b c d) 'e)\fP |
| 58 | (a b c d e) |
| 59 | .Ee |
| 60 | .Lf quote! "[g_qform\fIi\fP] ...[! 'g_eform\fIi\fP] ... [!! 'l_form\fIi\fP] ..." |
| 61 | .Re |
| 62 | The list resulting from the splicing and insertion process |
| 63 | described below. |
| 64 | .No |
| 65 | .i quote! |
| 66 | is the complement of the |
| 67 | .i list |
| 68 | function. |
| 69 | .i list |
| 70 | forms a list by evaluating each for in the argument list; evaluation is |
| 71 | suppressed if the form is \fIquote\fPed. In |
| 72 | .i quote!, |
| 73 | each form is implicitly \fIquote\fPed. To be evaluated, a form |
| 74 | must be preceded by one of the evaluate operations ! and !!. ! g_eform |
| 75 | evaluates g_form and the value is inserted in the place of the call; |
| 76 | !! l_form evaluates l_form and the value is spliced into the place of |
| 77 | the call. |
| 78 | .br |
| 79 | .sp |
| 80 | `Splicing in' means that the parentheses surrounding the list are removed |
| 81 | as the example below shows. |
| 82 | Use of the evaluate operators can occur at any level in a |
| 83 | form argument. |
| 84 | .br |
| 85 | .sp |
| 86 | Another way to get the effect of the \fIquote!\fP function is to use |
| 87 | the backquote character macro (see \(sc 8.3.3). |
| 88 | .Eb |
| 89 | \fI(quote! cons ! (cons 1 2) 3) = (cons (1 . 2) 3)\fP |
| 90 | \fI(quote! 1 !! (list 2 3 4) 5) = (1 2 3 4 5)\fP |
| 91 | \fI(setq quoted 'evaled)(quote! ! ((I am ! quoted))) = ((I am evaled))\fP |
| 92 | \fI(quote! try ! '(this ! one)) = (try (this ! one))\fP |
| 93 | .Ee |
| 94 | |
| 95 | .Lf bignum-to-list "'b_arg" |
| 96 | .Re |
| 97 | A list of the fixnums which are used to represent the bignum. |
| 98 | .No |
| 99 | the inverse of this function is |
| 100 | .i list-to-bignum. |
| 101 | .Lf list-to-bignum "'l_ints" |
| 102 | .Wh |
| 103 | l_ints is a list of fixnums. |
| 104 | .Re |
| 105 | a bignum constructed of the given fixnums. |
| 106 | .No |
| 107 | the inverse of this function is |
| 108 | .i bignum-to-list. |
| 109 | |
| 110 | .sh 3 list\ predicates |
| 111 | .Lf dtpr "'g_arg" |
| 112 | .Re |
| 113 | t iff g_arg is a list cell. |
| 114 | .No |
| 115 | that (dtpr '()) is nil. |
| 116 | .Lf listp "'g_arg" |
| 117 | .Re |
| 118 | t iff g_arg is a list object or nil. |
| 119 | .Lf tailp "'l_x 'l_y" |
| 120 | .Re |
| 121 | l_x, if a list cell |
| 122 | .i eq |
| 123 | to l_x is found by |
| 124 | .i cdr ing |
| 125 | down l_y zero or more times, nil otherwise. |
| 126 | .Eb |
| 127 | \-> \fI(setq x '(a b c d) y (cddr x))\fP |
| 128 | (c d) |
| 129 | \-> \fI(and (dtpr x) (listp x))\fP ; x and y are dtprs and lists |
| 130 | t |
| 131 | \-> \fI(dtpr '())\fP ; () is the same as nil and is not a dtpr |
| 132 | nil |
| 133 | \-> \fI(listp '())\fP ; however it is a list |
| 134 | t |
| 135 | \-> \fI(tailp y x)\fP |
| 136 | (c d) |
| 137 | .Ee |
| 138 | .Lf length "'l_arg" |
| 139 | .Re |
| 140 | the number of elements in the top level of list l_arg. |
| 141 | .sh 3 list\ accessing |
| 142 | .Lf car "'l_arg" |
| 143 | .Lx cdr "'l_arg" |
| 144 | .Re the appropriate part of |
| 145 | .i cons |
| 146 | cell. |
| 147 | (\fIcar\fP (\fIcons\fP x y)) is always x, |
| 148 | (\fIcdr\fP (\fIcons\fP x y)) is always y. |
| 149 | In |
| 150 | .Fr , |
| 151 | the cdr portion is located first in memory. |
| 152 | This is hardly noticeable, and seems to bother few. |
| 153 | .Lf c\.\.r "'lh_arg" |
| 154 | .Wh |
| 155 | the .. represents any positive number of \fBa\fP's and \fBd\fP's. |
| 156 | .Re |
| 157 | the result of accessing the list structure in the way determined by |
| 158 | the function name. |
| 159 | The \fBa\fP's and \fBd\fP's are read from right to left, a |
| 160 | .b d |
| 161 | directing the access down the cdr part of the list cell and an |
| 162 | .b a |
| 163 | down the car part. |
| 164 | .No |
| 165 | lh_arg may also be nil, and it is guaranteed that the car and cdr of nil |
| 166 | is nil. |
| 167 | If lh_arg is a hunk, then \fI(car\ 'lh_arg)\fP is the same as |
| 168 | \fI(cxr\ 1\ 'lh_arg)\fP and \fI(cdr\ 'lh_arg)\fP is the same |
| 169 | as \fI(cxr\ 0\ 'lh_arg)\fP. |
| 170 | .br |
| 171 | It is generally hard to read and understand the context |
| 172 | of functions with large strings of |
| 173 | .b a 's |
| 174 | and |
| 175 | .b d 's, |
| 176 | but these functions are supported by rapid accessing and open-compiling |
| 177 | (see Chapter 12). |
| 178 | .Lf nth "'x_index 'l_list" |
| 179 | .Re |
| 180 | the nth element of l_list, assuming zero-based index. |
| 181 | Thus (nth 0 l_list) is the same as (car l_list). |
| 182 | .i nth |
| 183 | is both a function, and a compiler macro, so that |
| 184 | more efficient code might be generated than for |
| 185 | .i nthelem |
| 186 | (described below). |
| 187 | .No |
| 188 | If x_arg1 is non-positive or greater than the length |
| 189 | of the list, nil is returned. |
| 190 | .Lf nthcdr "'x_index 'l_list" |
| 191 | .Re |
| 192 | the result of \fIcdr\fPing down the list l_list x_index times. |
| 193 | .No |
| 194 | If x_index is less than 0, then \fI(cons\ nil\ 'l_list)\fP is returned. |
| 195 | .Lf nthelem "'x_arg1 'l_arg2" |
| 196 | .Re |
| 197 | The x_arg1'\fIst\fP element of the list l_arg2. |
| 198 | .No |
| 199 | This function comes from the PDP-11 lisp system. |
| 200 | .Lf last "'l_arg" |
| 201 | .Re |
| 202 | the last list cell in the list l_arg. |
| 203 | .Ex |
| 204 | \fIlast\fP does NOT return the last element of a list! |
| 205 | .br |
| 206 | \fI(last '(a b))\fP = (b) |
| 207 | .Lf ldiff "'l_x 'l_y" |
| 208 | .Re |
| 209 | a list of all |
| 210 | elements in l_x but not in l_y |
| 211 | , i.e., the list difference of |
| 212 | l_x and l_y. |
| 213 | .No |
| 214 | l_y must be a tail of l_x, i.e., |
| 215 | .i eq |
| 216 | to the result of applying some number of \fIcdr\fP's |
| 217 | to l_x. |
| 218 | Note that the value of \fIldiff\fP is always new list |
| 219 | structure unless l_y is nil, in which case \fI(ldiff l_x nil)\fP is l_x |
| 220 | itself. |
| 221 | If l_y is not a tail of l_x, \fIldiff\fP generates an error. |
| 222 | .Ex |
| 223 | \fI(ldiff 'l_x (member 'g_foo 'l_x))\fP gives all elements |
| 224 | in l_x up to the first g_foo. |
| 225 | .sh 3 list\ manipulation |
| 226 | .Lf rplaca "'lh_arg1 'g_arg2" |
| 227 | .Re |
| 228 | the modified lh_arg1. |
| 229 | .Se |
| 230 | the car of lh_arg1 is set to g_arg2. |
| 231 | If lh_arg1 is a hunk then the second element of the hunk is set to g_arg2. |
| 232 | .Lf rplacd "'lh_arg1 'g_arg2" |
| 233 | .Re |
| 234 | the modified lh_arg1. |
| 235 | .Se |
| 236 | the cdr of lh_arg2 is set to g_arg2. |
| 237 | If lh_arg1 is a hunk then the first element of the hunk is set to g_arg2. |
| 238 | |
| 239 | .Lf attach "'g_x 'l_l" |
| 240 | .Re |
| 241 | l_l whose |
| 242 | .i car |
| 243 | is now g_x, whose |
| 244 | .i cadr |
| 245 | is the original \fI(car\ l_l)\fP, |
| 246 | and whose |
| 247 | .i cddr |
| 248 | is the original \fI(cdr\ l_l)\fP. |
| 249 | .No |
| 250 | what happens is that g_x is added to the |
| 251 | beginning of list l_l yet maintaining the same list cell at the |
| 252 | beginning of the list. |
| 253 | .Lf delete "'g_val 'l_list ['x_count]" |
| 254 | .Re |
| 255 | the result of splicing g_val from the top level of |
| 256 | l_list no more than x_count times. |
| 257 | .No |
| 258 | x_count defaults to a very large number, thus if x_count is not given, all |
| 259 | occurrences of g_val are removed from the top level of l_list. |
| 260 | g_val is compared with successive |
| 261 | .i car 's |
| 262 | of l_list using the function |
| 263 | .i equal . |
| 264 | .Se |
| 265 | l_list is modified using rplacd, no new list cells are used. |
| 266 | .Lf delq "'g_val 'l_list ['x_count]" |
| 267 | .Lx dremove "'g_val 'l_list ['x_count]" |
| 268 | .Re |
| 269 | the result of splicing g_val from the top level of l_list no more than |
| 270 | x_count times. |
| 271 | .No |
| 272 | .i delq |
| 273 | (and |
| 274 | .i dremove ) |
| 275 | are the same as |
| 276 | .i delete |
| 277 | except that |
| 278 | .i eq |
| 279 | is used for comparison instead of |
| 280 | .i equal . |
| 281 | .Eb |
| 282 | ; note that you should use the value returned by \fIdelete\fP or \fIdelq\fP |
| 283 | ; and not assume that g_val will always show the deletions. |
| 284 | ; For example |
| 285 | |
| 286 | \-> \fI(setq test '(a b c a d e))\fP |
| 287 | (a b c a d e) |
| 288 | \-> \fI(delete 'a test)\fP |
| 289 | (b c d e) ; the value returned is what we would expect |
| 290 | \-> \fItest\fP |
| 291 | (a b c d e) ; but test still has the first a in the list! |
| 292 | .Ee |
| 293 | .Lf remq "'g_x 'l_l ['x_count]" |
| 294 | .Lx remove "'g_x 'l_l" |
| 295 | .Re |
| 296 | a |
| 297 | .i copy |
| 298 | of l_l with all top level elements |
| 299 | .i equal |
| 300 | to g_x removed. |
| 301 | .i remq |
| 302 | uses |
| 303 | .i eq |
| 304 | instead of |
| 305 | .i equal |
| 306 | for comparisons. |
| 307 | .No |
| 308 | remove does not modify its arguments like |
| 309 | .i delete , |
| 310 | and |
| 311 | .i delq |
| 312 | do. |
| 313 | .Lf insert "'g_object 'l_list 'u_comparefn 'g_nodups" |
| 314 | .Re |
| 315 | a list consisting of l_list with g_object destructively inserted |
| 316 | in a place determined by the ordering function u_comparefn. |
| 317 | .No |
| 318 | \fI(comparefn 'g_x 'g_y)\fP |
| 319 | should return something non-nil if g_x can precede g_y in sorted order, |
| 320 | nil if g_y must precede g_x. |
| 321 | If u_comparefn is nil, alphabetical order |
| 322 | will be used. |
| 323 | If g_nodups is non-nil, an element will not be inserted if an |
| 324 | equal element is already in the list. |
| 325 | .i insert |
| 326 | does binary search to determine where to insert the new element. |
| 327 | .Lf merge "'l_data1 'l_data2 'u_comparefn" |
| 328 | .Re |
| 329 | the merged list of the two input sorted lists l_data1 and l_data1 |
| 330 | using binary comparison function u_comparefn. |
| 331 | .No |
| 332 | \fI(comparefn 'g_x 'g_y)\fP |
| 333 | should return something non-nil if g_x can precede g_y in sorted order, |
| 334 | nil if g_y must precede g_x. If u_comparefn is nil, |
| 335 | alphabetical order |
| 336 | will be used. u_comparefn should be thought of as "less than or equal". |
| 337 | .i merge |
| 338 | changes both of its data arguments. |
| 339 | .Lf subst "'g_x 'g_y 'l_s" |
| 340 | .Lx dsubst "'g_x 'g_y 'l_s" |
| 341 | .Re |
| 342 | the result of substituting g_x for all |
| 343 | .i equal |
| 344 | occurrences of g_y at all levels in l_s. |
| 345 | .No |
| 346 | If g_y is a symbol, |
| 347 | .i eq |
| 348 | will be used for comparisons. |
| 349 | The function |
| 350 | .i subst |
| 351 | does not modify l_s |
| 352 | but the function |
| 353 | .i dsubst |
| 354 | (destructive substitution) |
| 355 | does. |
| 356 | .Lf lsubst "'l_x 'g_y 'l_s" |
| 357 | .Re |
| 358 | a copy of l_s with l_x spliced in for every occurrence of of g_y |
| 359 | at all levels. |
| 360 | Splicing in means that the parentheses surrounding the list l_x are removed |
| 361 | as the example below shows. |
| 362 | .Eb |
| 363 | \-> \fI(subst '(a b c) 'x '(x y z (x y z) (x y z)))\fP |
| 364 | ((a b c) y z ((a b c) y z) ((a b c) y z)) |
| 365 | \-> \fI(lsubst '(a b c) 'x '(x y z (x y z) (x y z)))\fP |
| 366 | (a b c y z (a b c y z) (a b c y z)) |
| 367 | .Ee |
| 368 | .Lf subpair "'l_old 'l_new 'l_expr" |
| 369 | .Wh |
| 370 | there are the same number of elements in l_old as l_new. |
| 371 | .Re |
| 372 | the list l_expr with all occurrences of a object in l_old replaced by |
| 373 | the corresponding one in l_new. |
| 374 | When a substitution is made, a copy of the value to substitute in |
| 375 | is not made. |
| 376 | .Ex |
| 377 | \fI(subpair '(a c)' (x y) '(a b c d)) = (x b y d)\fP |
| 378 | |
| 379 | .Lf nconc "'l_arg1 'l_arg2 ['l_arg3 ...]" |
| 380 | .Re |
| 381 | A list consisting of the elements of l_arg1 followed by the elements of |
| 382 | l_arg2 followed by l_arg3 and so on. |
| 383 | .No |
| 384 | The |
| 385 | .i cdr |
| 386 | of the last list cell of l_arg\fIi\fP is changed to point to |
| 387 | l_arg\fIi+1\fP. |
| 388 | .Eb |
| 389 | ; \fInconc\fP is faster than \fIappend\fP because it doesn't allocate new list cells. |
| 390 | \-> \fI(setq lis1 '(a b c))\fP |
| 391 | (a b c) |
| 392 | \-> \fI(setq lis2 '(d e f))\fP |
| 393 | (d e f) |
| 394 | \-> \fI(append lis1 lis2)\fP |
| 395 | (a b c d e f) |
| 396 | \-> \fIlis1\fP |
| 397 | (a b c) ; note that lis1 has not been changed by \fIappend\fP |
| 398 | \-> \fI(nconc lis1 lis2)\fP |
| 399 | (a b c d e f) ; \fInconc\fP returns the same value as \fIappend\fP |
| 400 | \-> \fIlis1\fP |
| 401 | (a b c d e f) ; but in doing so alters lis1 |
| 402 | .Ee |
| 403 | |
| 404 | .Lf reverse "'l_arg" |
| 405 | .Lx nreverse "'l_arg" |
| 406 | .Re |
| 407 | the list l_arg with the elements at the top |
| 408 | level in reverse order. |
| 409 | .No |
| 410 | The function |
| 411 | .i nreverse |
| 412 | does the reversal in place, |
| 413 | that is the list structure is modified. |
| 414 | .Lf nreconc "'l_arg 'g_arg" |
| 415 | .Eq |
| 416 | \fI(nconc (nreverse 'l_arg) 'g_arg)\fP |
| 417 | |
| 418 | .sh 2 Predicates |
| 419 | .pp |
| 420 | The following functions test for properties of data objects. |
| 421 | When the result of the test is either 'false' or 'true', then |
| 422 | \fBnil\fP will be returned for 'false' and something other than |
| 423 | \fBnil\fP (often \fBt\fP) will be returned for 'true'. |
| 424 | .Lf arrayp "'g_arg" |
| 425 | .Re |
| 426 | t iff g_arg is of type array. |
| 427 | .Lf atom "'g_arg" |
| 428 | .Re |
| 429 | t iff g_arg is not a list or hunk object. |
| 430 | .No |
| 431 | \fI(atom '())\fP returns t. |
| 432 | .Lf bcdp "'g_arg" |
| 433 | .Re |
| 434 | t iff g_arg is a data object of type binary. |
| 435 | .No |
| 436 | the name of this function is a throwback to the PDP-11 Lisp system. |
| 437 | .Lf bigp "'g_arg" |
| 438 | .Re |
| 439 | t iff g_arg is a bignum. |
| 440 | .Lf dtpr "'g_arg" |
| 441 | .Re |
| 442 | t iff g_arg is a list cell. |
| 443 | .No |
| 444 | that (dtpr '()) is nil. |
| 445 | .Lf hunkp "'g_arg" |
| 446 | .Re |
| 447 | t iff g_arg is a hunk. |
| 448 | .Lf listp "'g_arg" |
| 449 | .Re |
| 450 | t iff g_arg is a list object or nil. |
| 451 | .Lf stringp "'g_arg" |
| 452 | .Re |
| 453 | t iff g_arg is a string. |
| 454 | .Lf symbolp "'g_arg" |
| 455 | .Re |
| 456 | t iff g_arg is a symbol. |
| 457 | .Lf valuep "'g_arg" |
| 458 | .Re |
| 459 | t iff g_arg is a value cell |
| 460 | .Lf vectorp 'v_vector |
| 461 | .Re |
| 462 | \fBt\fP iff the argument is a vector. |
| 463 | .Lf vectorip 'v_vector |
| 464 | .Re |
| 465 | \fBt\fP iff the argument is an immediate-vector. |
| 466 | .Lf type "'g_arg" |
| 467 | .Lx typep "'g_arg" |
| 468 | .Re |
| 469 | a symbol whose pname describes the type of g_arg. |
| 470 | .Lf signp "s_test 'g_val" |
| 471 | .Re |
| 472 | t iff g_val is a number and the given test s_test on g_val returns true. |
| 473 | .No |
| 474 | The fact that |
| 475 | .i signp |
| 476 | simply returns nil if g_val is not a number is probably the most |
| 477 | important reason that |
| 478 | .i signp |
| 479 | is used. |
| 480 | The permitted values for s_test and what they mean are given in this table. |
| 481 | .TS |
| 482 | center box; |
| 483 | l l . |
| 484 | s_test tested |
| 485 | |
| 486 | = |
| 487 | l g_val < 0 |
| 488 | le g_val \(<= 0 |
| 489 | e g_val = 0 |
| 490 | n g_val \(!= 0 |
| 491 | ge g_val \(>= 0 |
| 492 | g g_val > 0 |
| 493 | .TE |
| 494 | .Lf eq "'g_arg1 'g_arg2" |
| 495 | .Re |
| 496 | t if g_arg1 and g_arg2 are the exact same lisp object. |
| 497 | .No |
| 498 | .i Eq |
| 499 | simply tests if g_arg1 and g_arg2 are located in the exact same |
| 500 | place in memory. |
| 501 | Lisp objects which print the same are not necessarily |
| 502 | .i eq . |
| 503 | The only objects guaranteed to be |
| 504 | .i eq |
| 505 | are interned symbols with the same print name. |
| 506 | [Unless a symbol is created in a special way (such as with |
| 507 | .i uconcat |
| 508 | or |
| 509 | .i maknam ) |
| 510 | it will be interned.] |
| 511 | .Lf neq "'g_x 'g_y" |
| 512 | .Re |
| 513 | t if g_x is not |
| 514 | .i eq |
| 515 | to g_y, otherwise nil. |
| 516 | .Lf equal "'g_arg1 'g_arg2" |
| 517 | .Lx eqstr "'g_arg1 'g_arg2" |
| 518 | .Re |
| 519 | t iff g_arg1 and g_arg2 have the same structure as described below. |
| 520 | .No |
| 521 | g_arg and g_arg2 are |
| 522 | .i equal |
| 523 | if |
| 524 | .np |
| 525 | they are \fIeq\fP. |
| 526 | .np |
| 527 | they are both fixnums with the same value |
| 528 | .np |
| 529 | they are both flonums with the same value |
| 530 | .np |
| 531 | they are both bignums with the same value |
| 532 | .np |
| 533 | they are both strings and are identical. |
| 534 | .np |
| 535 | they are both lists and their cars and cdrs are |
| 536 | .i equal . |
| 537 | .Eb |
| 538 | ; \fIeq\fP is much faster than \fIequal\fP, especially in compiled code, |
| 539 | ; however you cannot use \fIeq\fP to test for equality of numbers outside |
| 540 | ; of the range -1024 to 1023. \fIequal\fP will always work. |
| 541 | \-> \fI(eq 1023 1023)\fP |
| 542 | t |
| 543 | \-> \fI(eq 1024 1024)\fP |
| 544 | nil |
| 545 | \-> \fI(equal 1024 1024)\fP |
| 546 | t |
| 547 | .Ee |
| 548 | |
| 549 | .Lf not "'g_arg" |
| 550 | .Lx null "'g_arg" |
| 551 | .Re |
| 552 | t iff g_arg is nil. |
| 553 | |
| 554 | .Lf member "'g_arg1 'l_arg2" |
| 555 | .Lx memq "'g_arg1 'l_arg2" |
| 556 | .Re |
| 557 | that part of the l_arg2 beginning with the first occurrence |
| 558 | of g_arg1. |
| 559 | If g_arg1 is not in the top level of l_arg2, nil is returned. |
| 560 | .No |
| 561 | .i member |
| 562 | tests for equality with |
| 563 | .i equal , |
| 564 | .i memq |
| 565 | tests for equality with |
| 566 | .i eq . |
| 567 | |
| 568 | .sh 2 Symbols\ and\ Strings |
| 569 | .pp |
| 570 | In many of the following functions the distinction between symbols and |
| 571 | strings is somewhat blurred. |
| 572 | To remind ourselves of the difference, |
| 573 | a string is a null terminated sequence of characters, stored as |
| 574 | compactly as possible. |
| 575 | Strings are used as constants in |
| 576 | .Fr . |
| 577 | They |
| 578 | .i eval |
| 579 | to themselves. |
| 580 | A symbol has additional structure: |
| 581 | a value, property list, function binding, |
| 582 | as well as its external representation (or print-name). |
| 583 | If a symbol is given to one of the string manipulation functions below, its |
| 584 | print name will be used. |
| 585 | .pp |
| 586 | Another popular way to represent strings in Lisp is as a list of fixnums |
| 587 | which represent characters. |
| 588 | The suffix 'n' to a string manipulation function indicates that it |
| 589 | returns a string in this form. |
| 590 | .sh 3 symbol\ and\ string\ creation |
| 591 | .Lf concat "['stn_arg1 ... ]" |
| 592 | .Lx uconcat "['stn_arg1 ... ]" |
| 593 | .Re |
| 594 | a symbol whose print name |
| 595 | is the result of concatenating the print names, |
| 596 | string characters or numerical representations |
| 597 | of the sn_arg\fIi\fP. |
| 598 | .No |
| 599 | If no arguments are given, a symbol with a null pname is returned. |
| 600 | \fIconcat\fP places the symbol created on the oblist, the function |
| 601 | .i uconcat |
| 602 | does the same thing but does not place the new symbol on the oblist. |
| 603 | .Ex |
| 604 | \fI(concat 'abc (add 3 4) "def")\fP = abc7def |
| 605 | .Lf concatl "'l_arg" |
| 606 | .Eq |
| 607 | \fI(apply 'concat 'l_arg)\fP |
| 608 | |
| 609 | .Lf implode "'l_arg" |
| 610 | .Lx maknam "'l_arg" |
| 611 | .Wh |
| 612 | l_arg is a list of symbols, strings and small fixnums. |
| 613 | .Re |
| 614 | The symbol whose print name is the result of concatenating the |
| 615 | first characters of the print names of the symbols and strings |
| 616 | in the list. |
| 617 | Any fixnums are converted to the equivalent ascii character. |
| 618 | In order to concatenate entire strings or print names, use the |
| 619 | function |
| 620 | .i concat . |
| 621 | .No |
| 622 | .i implode |
| 623 | interns the symbol it creates, |
| 624 | .i maknam |
| 625 | does not. |
| 626 | .Lf gensym "['s_leader]" |
| 627 | .Re |
| 628 | a new uninterned atom beginning with the first character of s_leader's |
| 629 | pname, or beginning with g if s_leader is not given. |
| 630 | .No |
| 631 | The symbol looks like x0nnnnn where x is s_leader's first character and |
| 632 | nnnnn is the number of times you have called gensym. |
| 633 | .Lf copysymbol "'s_arg 'g_pred" |
| 634 | .Re |
| 635 | an uninterned symbol with the same print name as s_arg. |
| 636 | If g_pred is non nil, then the value, function binding |
| 637 | and property list of the new symbol are made |
| 638 | .i eq |
| 639 | to those of s_arg. |
| 640 | |
| 641 | .Lf ascii "'x_charnum" |
| 642 | .Wh |
| 643 | x_charnum is between 0 and 255. |
| 644 | .Re |
| 645 | a symbol whose print name is the single character whose fixnum |
| 646 | representation is x_charnum. |
| 647 | |
| 648 | .Lf intern "'s_arg" |
| 649 | .Re |
| 650 | s_arg |
| 651 | .Se |
| 652 | s_arg is put on the oblist if it is not already there. |
| 653 | .Lf remob "'s_symbol" |
| 654 | .Re |
| 655 | s_symbol |
| 656 | .Se |
| 657 | s_symbol is removed from the oblist. |
| 658 | .Lf rematom "'s_arg" |
| 659 | .Re |
| 660 | t if s_arg is indeed an atom. |
| 661 | .Se |
| 662 | s_arg is put on the free atoms list, effectively reclaiming an |
| 663 | atom cell. |
| 664 | .No |
| 665 | This function does |
| 666 | .i not |
| 667 | check to see if s_arg is on the oblist or is referenced anywhere. |
| 668 | Thus calling |
| 669 | .i rematom |
| 670 | on an atom in the oblist may result in disaster when that atom cell |
| 671 | is reused! |
| 672 | .sh 3 string\ and\ symbol\ predicates |
| 673 | .Lf boundp "'s_name" |
| 674 | .Re |
| 675 | nil if s_name is unbound, that is it has never be given a value. |
| 676 | If x_name has the value g_val, then (nil\ .\ g_val) is returned. |
| 677 | .Lf alphalessp "'st_arg1 'st_arg2" |
| 678 | .Re |
| 679 | t iff the `name' of st_arg1 is alphabetically less than the |
| 680 | name of st_arg2. |
| 681 | If st_arg is a symbol then its `name' is its print name. |
| 682 | If st_arg is a string, then its `name' is the string itself. |
| 683 | .sh 3 symbol\ and\ string\ accessing |
| 684 | .Lf symeval "'s_arg" |
| 685 | .Re |
| 686 | the value of symbol s_arg. |
| 687 | .No |
| 688 | It is illegal to ask for the value of an unbound symbol. |
| 689 | This function has the same effect as |
| 690 | .i eval , |
| 691 | but compiles into much more efficient code. |
| 692 | .Lf get_pname "'s_arg" |
| 693 | .Re |
| 694 | the string which is the print name of s_arg. |
| 695 | .Lf plist "'s_arg" |
| 696 | .Re |
| 697 | the property list of s_arg. |
| 698 | .Lf getd "'s_arg" |
| 699 | .Re |
| 700 | the function definition of s_arg or nil if there is no function definition. |
| 701 | .No |
| 702 | the function definition may turn out to be an array header. |
| 703 | .Lf getchar "'s_arg 'x_index" |
| 704 | .Lx nthchar "'s_arg 'x_index" |
| 705 | .Lx getcharn "'s_arg 'x_index" |
| 706 | .Re |
| 707 | the x_index\fIth\fP character of the print name of s_arg or nil if x_index |
| 708 | is less than 1 or greater than the length of s_arg's print name. |
| 709 | .No |
| 710 | .i getchar |
| 711 | and |
| 712 | .i nthchar |
| 713 | return a symbol with a single character print name, |
| 714 | .i getcharn |
| 715 | returns the fixnum representation of the character. |
| 716 | .Lf substring "'st_string 'x_index ['x_length]" |
| 717 | .Lx substringn "'st_string 'x_index ['x_length]" |
| 718 | .Re |
| 719 | a string of length at most |
| 720 | x_length starting at x_index\fIth\fP character |
| 721 | in the string. |
| 722 | .No |
| 723 | If x_length is not given, all of the characters for x_index |
| 724 | to the end of the string are returned. |
| 725 | If x_index is negative the string begins at the |
| 726 | x_index\fIth\fP character from the end. |
| 727 | If x_index is out of bounds, nil is returned. |
| 728 | .No |
| 729 | .i substring |
| 730 | returns a list of symbols, |
| 731 | .i substringn |
| 732 | returns a list of fixnums. |
| 733 | If |
| 734 | .i substringn |
| 735 | is given a 0 x_length argument then a single fixnum |
| 736 | which is the x_index\fIth\fP character is returned. |
| 737 | .sh 3 symbol\ and\ string\ manipulation |
| 738 | .Lf set "'s_arg1 'g_arg2" |
| 739 | .Re |
| 740 | g_arg2. |
| 741 | .Se |
| 742 | the value of s_arg1 is set to g_arg2. |
| 743 | .Lf setq "s_atm1 'g_val1 [ s_atm2 'g_val2 ... ... ]" |
| 744 | .Wh |
| 745 | the arguments are pairs of atom names and expressions. |
| 746 | .Re |
| 747 | the last g_val\fIi\fP. |
| 748 | .Se |
| 749 | each s_atm\fIi\fP is set to have the value g_val\fIi\fP. |
| 750 | .No |
| 751 | .i set |
| 752 | evaluates all of its arguments, |
| 753 | .i setq |
| 754 | does not evaluate the s_atm\fIi\fP. |
| 755 | .Lf desetq "sl_pattern1 'g_exp1 [... ...]" |
| 756 | .Re |
| 757 | g_expn |
| 758 | .Se |
| 759 | This acts just like \fIsetq\fP if all the sl_pattern\fIi\fP are symbols. |
| 760 | If sl_pattern\fIi\fP is a list then it is a template which should |
| 761 | have the same structure as g_exp\fIi\fP |
| 762 | The symbols in sl_pattern are assigned to the corresponding |
| 763 | parts of g_exp. |
| 764 | .Ex |
| 765 | \fI(desetq (a b (c . d)) '(1 2 (3 4 5)))\fP |
| 766 | .br |
| 767 | sets a to 1, b to 2, c to 3, and d to (4 5). |
| 768 | |
| 769 | .Lf setplist "'s_atm 'l_plist" |
| 770 | .Re |
| 771 | l_plist. |
| 772 | .Se |
| 773 | the property list of s_atm is set to l_plist. |
| 774 | .Lf makunbound "'s_arg" |
| 775 | .Re |
| 776 | s_arg |
| 777 | .Se |
| 778 | the value of s_arg is made `unbound'. |
| 779 | If the interpreter attempts to evaluate s_arg before it is again |
| 780 | given a value, an unbound variable error will occur. |
| 781 | .Lf aexplode "'s_arg" |
| 782 | .Lx explode "'g_arg" |
| 783 | .Lx aexplodec "'s_arg" |
| 784 | .Lx explodec "'g_arg" |
| 785 | .Lx aexploden "'s_arg" |
| 786 | .Lx exploden "'g_arg" |
| 787 | .Re |
| 788 | a list of the characters used to print out s_arg or g_arg. |
| 789 | .No |
| 790 | The functions beginning with 'a' are internal functions which are limited |
| 791 | to symbol arguments. |
| 792 | The functions |
| 793 | .i aexplode |
| 794 | and |
| 795 | .i explode |
| 796 | return a list of characters which |
| 797 | .i print |
| 798 | would use to print the argument. |
| 799 | These characters include all necessary escape characters. |
| 800 | Functions |
| 801 | .i aexplodec |
| 802 | and |
| 803 | .i explodec |
| 804 | return a list of characters which |
| 805 | .i patom |
| 806 | would use to print the argument (i.e. no escape characters). |
| 807 | Functions |
| 808 | .i aexploden |
| 809 | and |
| 810 | .i exploden |
| 811 | are similar to |
| 812 | .i aexplodec |
| 813 | and |
| 814 | .i explodec |
| 815 | except that a list of fixnum equivalents of characters are returned. |
| 816 | .Eb |
| 817 | \-> \fI(setq x '|quote this \e| ok?|)\fP |
| 818 | |quote this \e| ok?| |
| 819 | \-> \fI(explode x)\fP |
| 820 | (q u o t e |\e\e| | | t h i s |\e\e| | | |\e\e| |\e|| |\e\e| | | o k ?) |
| 821 | ; note that |\e\e| just means the single character: backslash. |
| 822 | ; and |\e|| just means the single character: vertical bar |
| 823 | ; and | | means the single character: space |
| 824 | |
| 825 | \-> \fI(explodec x)\fP |
| 826 | (q u o t e | | t h i s | | |\e|| | | o k ?) |
| 827 | \-> \fI(exploden x)\fP |
| 828 | (113 117 111 116 101 32 116 104 105 115 32 124 32 111 107 63) |
| 829 | .Ee |
| 830 | .sh 2 Vectors |
| 831 | .pp |
| 832 | See Chapter 9 for a discussion of vectors. |
| 833 | They are intermediate in efficiency between arrays and hunks. |
| 834 | .sh 3 vector\ creation |
| 835 | .Lf new-vector "'x_size ['g_fill ['g_prop]]" |
| 836 | .Re |
| 837 | A \fBvector\fP of length x_size. |
| 838 | Each data entry is initialized to g_fill, or to nil, if the argument g_fill |
| 839 | is not present. |
| 840 | The vector's property is set to g_prop, or to nil, by default. |
| 841 | .Lf new-vectori-byte "'x_size ['g_fill ['g_prop]]" |
| 842 | .Lx new-vectori-word "'x_size ['g_fill ['g_prop]]" |
| 843 | .Lx new-vectori-long "'x_size ['g_fill ['g_prop]]" |
| 844 | .Re |
| 845 | A \fBvectori\fP with x_size elements in it. |
| 846 | The actual memory requirement is two long words + x_size*(n bytes), |
| 847 | where n is 1 for new-vector-byte, 2 for new-vector-word, or 4 for |
| 848 | new-vectori-long. |
| 849 | Each data entry is initialized to g_fill, or to zero, if the argument g_fill |
| 850 | is not present. |
| 851 | The vector's property is set to g_prop, or nil, by default. |
| 852 | .sp 2v |
| 853 | .lp |
| 854 | Vectors may be created by specifying multiple initial values: |
| 855 | .Lf vector "['g_val0 'g_val1 ...]" |
| 856 | .Re |
| 857 | a \fBvector\fP, with as many data elements as there are arguments. |
| 858 | It is quite possible to have a vector with no data elements. |
| 859 | The vector's property will be null. |
| 860 | .Lf vectori-byte "['x_val0 'x_val2 ...]" |
| 861 | .Lx vectori-word "['x_val0 'x_val2 ...]" |
| 862 | .Lx vectori-long "['x_val0 'x_val2 ...]" |
| 863 | .Re |
| 864 | a \fBvectori\fP, with as many data elements as there are arguments. |
| 865 | The arguments are required to be fixnums. |
| 866 | Only the low order byte or word is used in the case of vectori-byte |
| 867 | and vectori-word. |
| 868 | The vector's property will be null. |
| 869 | .sh 3 vector\ reference |
| 870 | .Lf vref "'v_vect 'x_index" |
| 871 | .Lx vrefi-byte "'V_vect 'x_bindex" |
| 872 | .Lx vrefi-word "'V_vect 'x_windex" |
| 873 | .Lx vrefi-long "'V_vect 'x_lindex" |
| 874 | .Re |
| 875 | the desired data element from a vector. |
| 876 | The indices must be fixnums. |
| 877 | Indexing is zero-based. |
| 878 | The vrefi functions sign extend the data. |
| 879 | .Lf vprop 'Vv_vect |
| 880 | .Re |
| 881 | The Lisp property associated with a vector. |
| 882 | .Lf vget "'Vv_vect 'g_ind" |
| 883 | .Re |
| 884 | The value stored under g_ind if the Lisp property associated |
| 885 | with 'Vv_vect is a disembodied property list. |
| 886 | .Lf vsize 'Vv_vect |
| 887 | .Lx vsize-byte 'V_vect |
| 888 | .Lx vsize-word 'V_vect |
| 889 | .Re |
| 890 | the number of data elements in the vector. For immediate-vectors, |
| 891 | the functions vsize-byte and vsize-word return the number of data elements, |
| 892 | if one thinks of the binary data as being comprised of bytes or words. |
| 893 | .sh 3 vector\ modfication |
| 894 | .Lf vset "'v_vect 'x_index 'g_val" |
| 895 | .Lx vseti-byte "'V_vect 'x_bindex 'x_val" |
| 896 | .Lx vseti-word "'V_vect 'x_windex 'x_val" |
| 897 | .Lx vseti-long "'V_vect 'x_lindex 'x_val" |
| 898 | .Re |
| 899 | the datum. |
| 900 | .Se |
| 901 | The indexed element of the vector is set to the value. |
| 902 | As noted above, for vseti-word and vseti-byte, the index |
| 903 | is construed as the number of the data element within |
| 904 | the vector. It is not a byte address. |
| 905 | Also, for those two functions, |
| 906 | the low order byte or word of x_val is what is stored. |
| 907 | .Lf vsetprop "'Vv_vect 'g_value" |
| 908 | .Re |
| 909 | g_value. This should be either a symbol |
| 910 | or a disembodied property list whose |
| 911 | .i car |
| 912 | is a symbol identifying the type of |
| 913 | the vector. |
| 914 | .Se |
| 915 | the property list of Vv_vect is set to g_value. |
| 916 | .Lf vputprop "'Vv_vect 'g_value 'g_ind" |
| 917 | .Re |
| 918 | g_value. |
| 919 | .Se |
| 920 | If the vector property of Vv_vect is a disembodied property list, |
| 921 | then vputprop adds the value g_value under the indicator g_ind. |
| 922 | Otherwise, the old vector property is made the first |
| 923 | element of the list. |
| 924 | .sh 2 Arrays |
| 925 | .pp |
| 926 | See Chapter 9 for a complete description of arrays. |
| 927 | Some of these functions are part of a Maclisp array |
| 928 | compatibility package, which represents only one simple way of using the |
| 929 | array structure of |
| 930 | .Fr . |
| 931 | .sh 3 array\ creation |
| 932 | .Lf marray "'g_data 's_access 'g_aux 'x_length 'x_delta" |
| 933 | .Re |
| 934 | an array type with the fields set up from the above arguments |
| 935 | in the obvious way (see \(sc 1.2.10). |
| 936 | .Lf *array "'s_name 's_type 'x_dim1 ... 'x_dim\fIn\fP" |
| 937 | .Lx array "s_name s_type x_dim1 ... x_dim\fIn\fP" |
| 938 | .Wh |
| 939 | s_type may be one of t, nil, fixnum, flonum, fixnum-block and |
| 940 | flonum-block. |
| 941 | .Re |
| 942 | an array of type s_type with n dimensions of extents given by the |
| 943 | x_dim\fIi\fP. |
| 944 | .Se |
| 945 | If s_name is non nil, the function definition of s_name is |
| 946 | set to the array structure returned. |
| 947 | .No |
| 948 | These |
| 949 | functions create a Maclisp compatible array. |
| 950 | In |
| 951 | .Fr |
| 952 | arrays of type t, nil, fixnum and flonum are equivalent and the elements |
| 953 | of these arrays can be any type of lisp object. |
| 954 | Fixnum-block and flonum-block arrays are restricted to fixnums and flonums |
| 955 | respectively and are used mainly to communicate with |
| 956 | foreign functions (see \(sc8.5). |
| 957 | .No |
| 958 | .i *array |
| 959 | evaluates its arguments, |
| 960 | .i array |
| 961 | does not. |
| 962 | .sh 3 array\ predicate |
| 963 | .Lf arrayp "'g_arg" |
| 964 | .Re |
| 965 | t iff g_arg is of type array. |
| 966 | .sh 3 array\ accessors |
| 967 | |
| 968 | .Lf getaccess "'a_array" |
| 969 | .Lx getaux "'a_array" |
| 970 | .Lx getdelta "'a_array" |
| 971 | .Lx getdata "'a_array" |
| 972 | .Lx getlength "'a_array" |
| 973 | .Re |
| 974 | the field of the array object a_array given by the function name. |
| 975 | .Lf arrayref "'a_name 'x_ind" |
| 976 | .Re |
| 977 | the x_ind\fIth\fP element of the array object a_name. |
| 978 | x_ind of zero accesses the first element. |
| 979 | .No |
| 980 | .i arrayref |
| 981 | uses the data, length and delta fields of a_name to determine which |
| 982 | object to return. |
| 983 | .Lf arraycall "s_type 'as_array 'x_ind1 ... " |
| 984 | .Re |
| 985 | the element selected by the indicies from the array a_array |
| 986 | of type s_type. |
| 987 | .No |
| 988 | If as_array is a symbol then the function binding of this symbol should |
| 989 | contain an array object. |
| 990 | .br |
| 991 | s_type is ignored by |
| 992 | .i arraycall |
| 993 | but is included for compatibility with Maclisp. |
| 994 | .Lf arraydims "'s_name" |
| 995 | .Re |
| 996 | a list of the type and bounds of the array s_name. |
| 997 | .Lf listarray "'sa_array ['x_elements]" |
| 998 | .Re |
| 999 | a list of all of the elements in array sa_array. |
| 1000 | If x_elements |
| 1001 | is given, then only the first x_elements are returned. |
| 1002 | |
| 1003 | .Eb |
| 1004 | ; We will create a 3 by 4 array of general lisp objects |
| 1005 | \-> \fI(array ernie t 3 4)\fP |
| 1006 | array[12] |
| 1007 | |
| 1008 | ; the array header is stored in the function definition slot of the |
| 1009 | ; symbol ernie |
| 1010 | \-> \fI(arrayp (getd 'ernie))\fP |
| 1011 | t |
| 1012 | \-> \fI(arraydims (getd 'ernie))\fP |
| 1013 | (t 3 4) |
| 1014 | |
| 1015 | ; store in ernie[2][2] the list (test list) |
| 1016 | \-> \fI(store (ernie 2 2) '(test list))\fP |
| 1017 | (test list) |
| 1018 | |
| 1019 | ; check to see if it is there |
| 1020 | \-> \fI(ernie 2 2)\fP |
| 1021 | (test list) |
| 1022 | |
| 1023 | ; now use the low level function \fIarrayref\fP to find the same element |
| 1024 | ; arrays are 0 based and row-major (the last subscript varies the fastest) |
| 1025 | ; thus element [2][2] is the 10th element , (starting at 0). |
| 1026 | \-> \fI(arrayref (getd 'ernie) 10)\fP |
| 1027 | (ptr to)(test list) ; the result is a value cell (thus the (ptr to)) |
| 1028 | .Ee |
| 1029 | .sh 3 array\ manipulation |
| 1030 | .Lf putaccess "'a_array 'su_func" |
| 1031 | .Lx putaux "'a_array 'g_aux" |
| 1032 | .Lx putdata "'a_array 'g_arg" |
| 1033 | .Lx putdelta "'a_array 'x_delta" |
| 1034 | .Lx putlength "'a_array 'x_length" |
| 1035 | .Re |
| 1036 | the second argument to the function. |
| 1037 | .Se |
| 1038 | The field of the array object given by the function name is replaced |
| 1039 | by the second argument to the function. |
| 1040 | .Lf store "'l_arexp 'g_val" |
| 1041 | .Wh |
| 1042 | l_arexp is an expression |
| 1043 | which references an array element. |
| 1044 | .Re |
| 1045 | g_val |
| 1046 | .Se |
| 1047 | the array location which contains the element which l_arexp references is |
| 1048 | changed to contain g_val. |
| 1049 | .Lf fillarray "'s_array 'l_itms" |
| 1050 | .Re |
| 1051 | s_array |
| 1052 | .Se |
| 1053 | the array s_array is filled with elements from l_itms. |
| 1054 | If there are not enough elements in l_itms to fill the entire array, |
| 1055 | then the last element of l_itms is used to fill the remaining parts |
| 1056 | of the array. |
| 1057 | .sh 2 Hunks |
| 1058 | .pp |
| 1059 | Hunks are vector-like objects whose size can range from 1 to 128 elements. |
| 1060 | Internally hunks are allocated in sizes which are powers of 2. |
| 1061 | In order to create hunks of a given size, |
| 1062 | a hunk with at least that many elements is allocated |
| 1063 | and a distinguished symbol \s-2EMPTY\s0 is placed in those |
| 1064 | elements not requested. |
| 1065 | Most hunk functions respect those distinguished symbols, but there are |
| 1066 | two |
| 1067 | .i (*makhunk |
| 1068 | and |
| 1069 | .i *rplacx ) |
| 1070 | which will overwrite the distinguished symbol. |
| 1071 | .sh 3 hunk\ creation |
| 1072 | .Lf hunk "'g_val1 ['g_val2 ... 'g_val\fIn\fP]" |
| 1073 | .Re |
| 1074 | a hunk of length n whose elements are initialized to the g_val\fIi\fP. |
| 1075 | .No |
| 1076 | the maximum size of a hunk is 128. |
| 1077 | .Ex |
| 1078 | \fI(hunk 4 'sharp 'keys)\fP = {4 sharp keys} |
| 1079 | .Lf makhunk "'xl_arg" |
| 1080 | .Re |
| 1081 | a hunk of length xl_arg initialized to all nils if xl_arg is a fixnum. |
| 1082 | If xl_arg is a list, then we return a hunk of size \fI(length\ 'xl_arg)\fP |
| 1083 | initialized to the elements in xl_arg. |
| 1084 | .No |
| 1085 | \fI(makhunk\ '(a\ b\ c))\fP is equivalent to \fI(hunk\ 'a\ 'b\ 'c)\fP. |
| 1086 | .Ex |
| 1087 | \fI(makhunk 4)\fP = \fI{nil nil nil nil}\fP |
| 1088 | .Lf *makhunk "'x_arg" |
| 1089 | .Re |
| 1090 | a hunk of size 2\*[x_arg\*] initialized to \s-2EMPTY\s0. |
| 1091 | .No |
| 1092 | This is only to be used by such functions as \fIhunk\fP and \fImakhunk\fP |
| 1093 | which create and initialize hunks for users. |
| 1094 | .sh 3 hunk\ accessor |
| 1095 | .Lf cxr "'x_ind 'h_hunk" |
| 1096 | .Re |
| 1097 | element x_ind (starting at 0) of hunk h_hunk. |
| 1098 | .Lf hunk-to-list 'h_hunk |
| 1099 | .Re |
| 1100 | a list consisting of the elements of h_hunk. |
| 1101 | .sh 3 hunk\ manipulators |
| 1102 | .Lf rplacx "'x_ind 'h_hunk 'g_val" |
| 1103 | .Lx *rplacx "'x_ind 'h_hunk 'g_val" |
| 1104 | .Re |
| 1105 | h_hunk |
| 1106 | .Se |
| 1107 | Element x_ind (starting at 0) of h_hunk is set to g_val. |
| 1108 | .No |
| 1109 | .i rplacx |
| 1110 | will not modify one of the distinguished (EMPTY) elements |
| 1111 | whereas |
| 1112 | .i *rplacx |
| 1113 | will. |
| 1114 | .Lf hunksize "'h_arg" |
| 1115 | .Re |
| 1116 | the size of the hunk h_arg. |
| 1117 | .Ex |
| 1118 | \fI(hunksize (hunk 1 2 3))\fP = 3 |
| 1119 | .sh 2 Bcds |
| 1120 | .pp |
| 1121 | A bcd object contains a pointer to compiled code and to the type of |
| 1122 | function object the compiled code represents. |
| 1123 | .Lf getdisc "'y_bcd" |
| 1124 | .Lx getentry "'y_bcd" |
| 1125 | .Re |
| 1126 | the field of the bcd object given by the function name. |
| 1127 | .Lf putdisc "'y_func 's_discipline" |
| 1128 | .Re |
| 1129 | s_discipline |
| 1130 | .Se |
| 1131 | Sets the discipline field of y_func to s_discipline. |
| 1132 | .sh 2 Structures |
| 1133 | .pp |
| 1134 | There are three common structures constructed out of list cells: the |
| 1135 | assoc list, the property list and the tconc list. |
| 1136 | The functions below manipulate these structures. |
| 1137 | .sh 3 assoc\ list |
| 1138 | .pp |
| 1139 | An `assoc list' (or alist) is a common lisp data structure. It has the |
| 1140 | form |
| 1141 | .br |
| 1142 | .ce 1 |
| 1143 | ((key1 . value1) (key2 . value2) (key3 . value3) ... (keyn . valuen)) |
| 1144 | .Lf assoc "'g_arg1 'l_arg2" |
| 1145 | .Lx assq "'g_arg1 'l_arg2" |
| 1146 | .Re |
| 1147 | the first top level element of l_arg2 whose |
| 1148 | .i car |
| 1149 | is |
| 1150 | .i equal |
| 1151 | (with |
| 1152 | .i assoc ) |
| 1153 | or |
| 1154 | .i eq |
| 1155 | (with |
| 1156 | .i assq ) |
| 1157 | to g_arg1. |
| 1158 | .No |
| 1159 | Usually l_arg2 has an |
| 1160 | .i a-list |
| 1161 | structure and g_arg1 acts as key. |
| 1162 | .Lf sassoc "'g_arg1 'l_arg2 'sl_func" |
| 1163 | .Re |
| 1164 | the result of \fI(cond\ ((assoc\ 'g_arg\ 'l_arg2)\ (apply\ 'sl_func\ nil)))\fP |
| 1165 | .No |
| 1166 | sassoc is written as a macro. |
| 1167 | .Lf sassq "'g_arg1 'l_arg2 'sl_func" |
| 1168 | .Re |
| 1169 | the result of \fI(cond\ ((assq\ 'g_arg\ 'l_arg2)\ (apply\ 'sl_func\ nil)))\fP |
| 1170 | .No |
| 1171 | sassq is written as a macro. |
| 1172 | |
| 1173 | .Eb |
| 1174 | ; \fIassoc\fP or \fIassq\fP is given a key and an assoc list and returns |
| 1175 | ; the key and value item if it exists, they differ only in how they test |
| 1176 | ; for equality of the keys. |
| 1177 | |
| 1178 | \-> \fI(setq alist '((alpha . a) ( (complex key) . b) (junk . x)))\fP |
| 1179 | ((alpha . a) ((complex key) . b) (junk . x)) |
| 1180 | |
| 1181 | ; we should use \fIassq\fP when the key is an atom |
| 1182 | \-> \fI(assq 'alpha alist)\fP |
| 1183 | (alpha . a) |
| 1184 | |
| 1185 | ; but it may not work when the key is a list |
| 1186 | \-> \fI(assq '(complex key) alist)\fP |
| 1187 | nil |
| 1188 | |
| 1189 | ; however \fIassoc\fP will always work |
| 1190 | \-> \fI(assoc '(complex key) alist)\fP |
| 1191 | ((complex key) . b) |
| 1192 | .Ee |
| 1193 | .Lf sublis "'l_alst 'l_exp" |
| 1194 | .Wh |
| 1195 | l_alst is an |
| 1196 | .i a-list . |
| 1197 | .Re |
| 1198 | the list l_exp with every occurrence of key\fIi\fP replaced by val\fIi\fP. |
| 1199 | .No |
| 1200 | new list structure is returned to prevent modification of l_exp. |
| 1201 | When a substitution is made, a copy of the value to substitute in |
| 1202 | is not made. |
| 1203 | .sh 3 property\ list |
| 1204 | .pp |
| 1205 | A property list consists of an alternating sequence of keys and |
| 1206 | values. Normally a property list is stored on a symbol. A list |
| 1207 | is a 'disembodied' property list if it contains an odd number of |
| 1208 | elements, the first of which is ignored. |
| 1209 | .Lf plist "'s_name" |
| 1210 | .Re |
| 1211 | the property list of s_name. |
| 1212 | .Lf setplist "'s_atm 'l_plist" |
| 1213 | .Re |
| 1214 | l_plist. |
| 1215 | .Se |
| 1216 | the property list of s_atm is set to l_plist. |
| 1217 | |
| 1218 | .Lf get "'ls_name 'g_ind" |
| 1219 | .Re |
| 1220 | the value under indicator g_ind in ls_name's property list if ls_name |
| 1221 | is a symbol. |
| 1222 | .No |
| 1223 | If there is no indicator g_ind in ls_name's property list nil is returned. |
| 1224 | If ls_name is a list of an odd number of elements then it is a disembodied |
| 1225 | property list. |
| 1226 | \fIget\fP searches a disembodied property list by starting at its |
| 1227 | \fIcdr\fP, and comparing every other element with g_ind, using |
| 1228 | \fIeq\fP. |
| 1229 | .Lf getl "'ls_name 'l_indicators" |
| 1230 | .Re |
| 1231 | the property list ls_name beginning at the first indicator which is |
| 1232 | a member of the list l_indicators, or nil if none of the indicators |
| 1233 | in l_indicators are on ls_name's property list. |
| 1234 | .No |
| 1235 | If ls_name is a list, then it is assumed to be a disembodied property |
| 1236 | list. |
| 1237 | |
| 1238 | .Lf putprop "'ls_name 'g_val 'g_ind" |
| 1239 | .Lx defprop "ls_name g_val g_ind" |
| 1240 | .Re |
| 1241 | g_val. |
| 1242 | .Se |
| 1243 | Adds to the property list of ls_name the value g_val under the indicator |
| 1244 | g_ind. |
| 1245 | .No |
| 1246 | .i putprop |
| 1247 | evaluates it arguments, |
| 1248 | .i defprop |
| 1249 | does not. |
| 1250 | ls_name may be a disembodied property list, see \fIget\fP. |
| 1251 | .Lf remprop "'ls_name 'g_ind" |
| 1252 | .Re |
| 1253 | the portion of ls_name's property list beginning with the |
| 1254 | property under the indicator g_ind. |
| 1255 | If there is no g_ind indicator in ls_name's plist, nil is returned. |
| 1256 | .Se |
| 1257 | the value under indicator g_ind and g_ind itself is removed from |
| 1258 | the property list of ls_name. |
| 1259 | .No |
| 1260 | ls_name may be a disembodied property list, see \fIget\fP. |
| 1261 | |
| 1262 | .Eb |
| 1263 | \-> \fI(putprop 'xlate 'a 'alpha)\fP |
| 1264 | a |
| 1265 | \-> \fI(putprop 'xlate 'b 'beta)\fP |
| 1266 | b |
| 1267 | \-> \fI(plist 'xlate)\fP |
| 1268 | (alpha a beta b) |
| 1269 | \-> \fI(get 'xlate 'alpha)\fP |
| 1270 | a |
| 1271 | ; use of a disembodied property list: |
| 1272 | \-> \fI(get '(nil fateman rjf sklower kls foderaro jkf) 'sklower)\fP |
| 1273 | kls |
| 1274 | .Ee |
| 1275 | .sh 3 tconc\ structure |
| 1276 | .pp |
| 1277 | A tconc structure is a special type of list designed to make it |
| 1278 | easy to add objects to the end. |
| 1279 | It consists of a list cell whose |
| 1280 | .i car |
| 1281 | points to a |
| 1282 | list of the elements added with |
| 1283 | .i tconc |
| 1284 | or |
| 1285 | .i lconc |
| 1286 | and whose |
| 1287 | .i cdr |
| 1288 | points to the last list cell of the list pointed to by the |
| 1289 | .i car. |
| 1290 | .Lf tconc "'l_ptr 'g_x" |
| 1291 | .Wh |
| 1292 | l_ptr is a tconc structure. |
| 1293 | .Re |
| 1294 | l_ptr with g_x added to the end. |
| 1295 | .Lf lconc "'l_ptr 'l_x" |
| 1296 | .Wh |
| 1297 | l_ptr is a tconc structure. |
| 1298 | .Re |
| 1299 | l_ptr with the list l_x spliced in at the end. |
| 1300 | .Eb |
| 1301 | ; A \fItconc\fP structure can be initialized in two ways. |
| 1302 | ; nil can be given to \fItconc\fP in which case \fItconc\fP will generate |
| 1303 | ; a \fItconc\fP structure. |
| 1304 | |
| 1305 | \->\fI(setq foo (tconc nil 1))\fP |
| 1306 | ((1) 1) |
| 1307 | |
| 1308 | ; Since \fItconc\fP destructively adds to |
| 1309 | ; the list, you can now add to foo without using \fIsetq\fP again. |
| 1310 | |
| 1311 | \->\fI(tconc foo 2)\fP |
| 1312 | ((1 2) 2) |
| 1313 | \->\fIfoo\fP |
| 1314 | ((1 2) 2) |
| 1315 | |
| 1316 | ; Another way to create a null \fItconc\fP structure |
| 1317 | ; is to use \fI(ncons\ nil)\fP. |
| 1318 | |
| 1319 | \->\fI(setq foo (ncons nil))\fP |
| 1320 | (nil) |
| 1321 | \->\fI(tconc foo 1)\fP |
| 1322 | ((1) 1) |
| 1323 | |
| 1324 | ; now see what \fIlconc\fP can do |
| 1325 | \-> \fI(lconc foo nil)\fP |
| 1326 | ((1) 1) ; no change |
| 1327 | \-> \fI(lconc foo '(2 3 4))\fP |
| 1328 | ((1 2 3 4) 4) |
| 1329 | .Ee |
| 1330 | .sh 3 fclosures |
| 1331 | .pp |
| 1332 | An fclosure is a functional object which admits some data |
| 1333 | manipulations. They are discussed in \(sc8.4. |
| 1334 | Internally, they are constructed from vectors. |
| 1335 | .Lf fclosure "'l_vars 'g_funobj" |
| 1336 | .Wh |
| 1337 | l_vars is a list of variables, g_funobj is any object |
| 1338 | that can be funcalled (including, fclosures). |
| 1339 | .Re |
| 1340 | A vector which is the fclosure. |
| 1341 | .Lf fclosure-alist "'v_fclosure" |
| 1342 | .Re |
| 1343 | An association list representing the variables in the fclosure. |
| 1344 | This is a snapshot of the current state of the fclosure. |
| 1345 | If the bindings in the fclosure are changed, any previously |
| 1346 | calculated results of |
| 1347 | .i fclosure-alist |
| 1348 | will not change. |
| 1349 | .Lf fclosure-function "'v_fclosure" |
| 1350 | .Re |
| 1351 | the functional object part of the fclosure. |
| 1352 | .Lf fclosurep "'v_fclosure" |
| 1353 | .Re |
| 1354 | t iff the argument is an fclosure. |
| 1355 | .Lf symeval-in-fclosure "'v_fclosure 's_symbol" |
| 1356 | .Re |
| 1357 | the current binding of a particular symbol in an fclosure. |
| 1358 | .Lf set-in-fclosure "'v_fclosure 's_symbol 'g_newvalue" |
| 1359 | .Re |
| 1360 | g_newvalue. |
| 1361 | .Se |
| 1362 | The variable s_symbol is bound in the fclosure to g_newvalue. |
| 1363 | .sh 2 Random\ functions |
| 1364 | .pp |
| 1365 | The following functions don't fall into any of the classifications above. |
| 1366 | .Lf bcdad "'s_funcname" |
| 1367 | .Re |
| 1368 | a fixnum which is the address in memory where the function |
| 1369 | s_funcname begins. |
| 1370 | If s_funcname is not a machine coded function (binary) then |
| 1371 | .i bcdad |
| 1372 | returns nil. |
| 1373 | .Lf copy "'g_arg" |
| 1374 | .Re |
| 1375 | A structure |
| 1376 | .i equal |
| 1377 | to g_arg but with new list cells. |
| 1378 | .Lf copyint* "'x_arg" |
| 1379 | .Re |
| 1380 | a fixnum with the same value as x_arg but in a freshly allocated cell. |
| 1381 | .Lf cpy1 "'xvt_arg" |
| 1382 | .Re |
| 1383 | a new cell of the same type as xvt_arg with the same value as xvt_arg. |
| 1384 | .Lf getaddress "'s_entry1 's_binder1 'st_discipline1 [... ... ...]" |
| 1385 | .Re |
| 1386 | the binary object which s_binder1's function field is set to. |
| 1387 | .No |
| 1388 | This looks in the running lisp's symbol table for a symbol with the same |
| 1389 | name as s_entry\fIi\fP. |
| 1390 | It then creates a binary object |
| 1391 | whose entry field points to s_entry\fIi\fP |
| 1392 | and whose discipline is st_discipline\fIi\fP. |
| 1393 | This binary object is stored in the function field of s_binder\fIi\fP. |
| 1394 | If st_discipline\fIi\fP is nil, then "subroutine" is used by default. |
| 1395 | This is especially useful for |
| 1396 | .i cfasl |
| 1397 | users. |
| 1398 | .Lf macroexpand "'g_form" |
| 1399 | .Re |
| 1400 | g_form after all macros in it are |
| 1401 | expanded. |
| 1402 | .No |
| 1403 | This function will only macroexpand |
| 1404 | expressions which could be evaluated |
| 1405 | and it does not know about the special nlambdas such as |
| 1406 | .i cond |
| 1407 | and |
| 1408 | .i do , |
| 1409 | thus it misses many macro expansions. |
| 1410 | .Lf ptr "'g_arg" |
| 1411 | .Re |
| 1412 | a value cell initialized to point to g_arg. |
| 1413 | .Lf quote "g_arg" |
| 1414 | .Re |
| 1415 | g_arg. |
| 1416 | .No |
| 1417 | the reader allows you to abbreviate (quote foo) as 'foo. |
| 1418 | .Lf kwote "'g_arg" |
| 1419 | .Re |
| 1420 | \fI(list (quote quote) g_arg)\fP. |
| 1421 | .Lf replace "'g_arg1 'g_arg2" |
| 1422 | .Wh |
| 1423 | g_arg1 and g_arg2 must be the same type of lispval and not symbols or hunks. |
| 1424 | .Re |
| 1425 | g_arg2. |
| 1426 | .Se |
| 1427 | The effect of |
| 1428 | .i replace |
| 1429 | is dependent on the type of the g_arg\fIi\fP although one will notice |
| 1430 | a similarity in the effects. |
| 1431 | To understand what |
| 1432 | .i replace |
| 1433 | does to fixnum and flonum arguments, |
| 1434 | you must first understand that |
| 1435 | such numbers are `boxed' in |
| 1436 | .Fr . |
| 1437 | What this means is that if the symbol x has a value 32412, then in |
| 1438 | memory the value element of x's symbol structure contains the address of |
| 1439 | another word of memory (called a box) with 32412 in it. |
| 1440 | .br |
| 1441 | .sp |
| 1442 | Thus, there are two ways of changing the value of x: |
| 1443 | the first is to change |
| 1444 | the value element of x's symbol structure to point to a word of memory |
| 1445 | with a different value. |
| 1446 | The second way is to change the value in the box which x points to. |
| 1447 | The former method is used almost all of the time, the latter is |
| 1448 | used very rarely and has the potential to cause great confusion. |
| 1449 | The function |
| 1450 | .i replace |
| 1451 | allows you to do the latter, i.e., to actually change the value in |
| 1452 | the box. |
| 1453 | .br |
| 1454 | .sp |
| 1455 | You should watch out for these situations. |
| 1456 | If you do \fI(setq\ y\ x)\fP, |
| 1457 | then both x and y will point to the same box. |
| 1458 | If you now \fI(replace\ x\ 12345)\fP, |
| 1459 | then y will also have the value 12345. |
| 1460 | And, in fact, there may be many other pointers to that box. |
| 1461 | .br |
| 1462 | .sp |
| 1463 | Another problem with replacing fixnums |
| 1464 | is that some boxes are read-only. |
| 1465 | The fixnums between -1024 and 1023 are stored in a read-only area |
| 1466 | and attempts to replace them will result in an "Illegal memory reference" |
| 1467 | error (see the description of |
| 1468 | .i copyint* |
| 1469 | for a way around this problem). |
| 1470 | .br |
| 1471 | .sp |
| 1472 | For the other valid types, the effect of |
| 1473 | .i replace |
| 1474 | is easy to understand. |
| 1475 | The fields of g_val1's structure are made eq to the corresponding fields of |
| 1476 | g_val2's structure. |
| 1477 | For example, if x and y have lists as values then the effect of |
| 1478 | \fI(replace\ x\ y)\fP is the same as |
| 1479 | \fI(rplaca\ x\ (car\ y))\fP and \fI(rplacd\ x\ (cdr\ y))\fP. |
| 1480 | .Lf scons "'x_arg 'bs_rest" |
| 1481 | .Wh |
| 1482 | bs_rest is a bignum or nil. |
| 1483 | .Re |
| 1484 | a bignum whose first bigit is x_arg |
| 1485 | and whose higher order bigits are bs_rest. |
| 1486 | .Lf setf "g_refexpr 'g_value" |
| 1487 | .No |
| 1488 | .i setf |
| 1489 | is a generalization of setq. Information may be stored by |
| 1490 | binding variables, replacing entries of arrays, and vectors, |
| 1491 | or being put on property lists, among others. |
| 1492 | Setf will allow the user to store data into some location, |
| 1493 | by mentioning the operation used to refer to the location. |
| 1494 | Thus, the first argument may be partially evaluated, but only |
| 1495 | to the extent needed to calculate a reference. |
| 1496 | .i setf |
| 1497 | returns g_value. |
| 1498 | .Eb |
| 1499 | (setf x 3) = (setq x 3) |
| 1500 | (setf (car x) 3) = (rplaca x 3) |
| 1501 | (setf (get foo 'bar) 3) = (putprop foo 3 'bar) |
| 1502 | (setf (vref vector index) value) = (vset vector index value) |
| 1503 | .Ee |
| 1504 | .Lf sort "'l_data 'u_comparefn" |
| 1505 | .Re |
| 1506 | a list of the elements of l_data ordered by the comparison |
| 1507 | function u_comparefn |
| 1508 | .Se |
| 1509 | the list l_data is modified rather than allocate new storage. |
| 1510 | .No |
| 1511 | \fI(comparefn 'g_x 'g_y)\fP should return something |
| 1512 | non-nil if g-x can precede g_y in sorted order; nil if g_y must precede |
| 1513 | g_x. |
| 1514 | If u_comparefn is nil, |
| 1515 | alphabetical order will be used. |
| 1516 | .Lf sortcar "'l_list 'u_comparefn" |
| 1517 | .Re |
| 1518 | a list of the elements of l_list with the |
| 1519 | .i car 's |
| 1520 | ordered by the sort function u_comparefn. |
| 1521 | .Se |
| 1522 | the list l_list is modified rather than allocating new storage. |
| 1523 | .No |
| 1524 | Like \fIsort\fP, |
| 1525 | if u_comparefn is nil, |
| 1526 | alphabetical order will be used. |