projects / unix-history / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
BSD 4_3 development
[unix-history] / usr / lib / lisp / manual / ch2.r
CommitLineData
f9a8037d
C		 1
2
3
4
5
6
7
8 CHAPTER 2
9
10
11 Data Structure Access
12
13
14
15
16 The following functions allow one to create and manipu-
17late the various types of lisp data structures. Refer to
181.2 for details of the data structures known to FRANZ LISP.
19
20
21
22 2.1. Lists
23
24 The following functions exist for the creation
25 and manipulating of lists. Lists are composed of a
26 linked list of objects called either 'list cells',
27 'cons cells' or 'dtpr cells'. Lists are normally ter-
28 minated with the special symbol nil. nil is both a
29 symbol and a representation for the empty list ().
30
31
32
33 2.1.1. list creation
34
35(cons 'g_arg1 'g_arg2)
36
37 RETURNS: a new list cell whose car is g_arg1 and whose
38 cdr is g_arg2.
39
40(xcons 'g_arg1 'g_arg2)
41
42 EQUIVALENT TO: (_\bc_\bo_\bn_\bs '_\bg__\ba_\br_\bg_\b2 '_\bg__\ba_\br_\bg_\b1)
43
44(ncons 'g_arg)
45
46 EQUIVALENT TO: (_\bc_\bo_\bn_\bs '_\bg__\ba_\br_\bg _\bn_\bi_\bl)
47
48(list ['g_arg1 ... ])
49
50 RETURNS: a list whose elements are the g_arg_\bi.
51
52
53
54
55
56
57
58
59
60\e9
61
62\e9Data Structure Access 2-1
63
64
65
66
67
68
69
70Data Structure Access 2-2
71
72
73(append 'l_arg1 'l_arg2)
74
75 RETURNS: a list containing the elements of l_arg1 fol-
76 lowed by l_arg2.
77
78 NOTE: To generate the result, the top level list cells
79 of l_arg1 are duplicated and the cdr of the last
80 list cell is set to point to l_arg2. Thus this
81 is an expensive operation if l_arg1 is large.
82 See the descriptions of _\bn_\bc_\bo_\bn_\bc and _\bt_\bc_\bo_\bn_\bc for
83 cheaper ways of doing the _\ba_\bp_\bp_\be_\bn_\bd if the list
84 l_arg1 can be altered.
85
86(append1 'l_arg1 'g_arg2)
87
88 RETURNS: a list like l_arg1 with g_arg2 as the last
89 element.
90
91 NOTE: this is equivalent to (append 'l_arg1 (list
92 'g_arg2)).
93
94
95 ____________________________________________________
96
97 ; A common mistake is using append to add one element to the end of a list
98 -> (_\ba_\bp_\bp_\be_\bn_\bd '(_\ba _\bb _\bc _\bd) '_\be)
99 (a b c d . e)
100 ; The user intended to say:
101 -> (_\ba_\bp_\bp_\be_\bn_\bd '(_\ba _\bb _\bc _\bd) '(_\be))
102 (_\ba _\bb _\bc _\bd _\be)
103 ; _\bb_\be_\bt_\bt_\be_\br _\bi_\bs _\ba_\bp_\bp_\be_\bn_\bd_\b1
104 -> (_\ba_\bp_\bp_\be_\bn_\bd_\b1 '(_\ba _\bb _\bc _\bd) '_\be)
105 (_\ba _\bb _\bc _\bd _\be)
106 ____________________________________________________
107
108
109
110
111(quote! [g_qform_\bi] ...[! 'g_eform_\bi] ... [!! 'l_form_\bi] ...)
112
113 RETURNS: The list resulting from the splicing and
114 insertion process described below.
115
116 NOTE: _\bq_\bu_\bo_\bt_\be! is the complement of the _\bl_\bi_\bs_\bt function.
117 _\bl_\bi_\bs_\bt forms a list by evaluating each for in the
118 argument list; evaluation is suppressed if the
119 form is _\bq_\bu_\bo_\bt_\beed. In _\bq_\bu_\bo_\bt_\be!, each form is impli-
120 citly _\bq_\bu_\bo_\bt_\beed. To be evaluated, a form must be
121 preceded by one of the evaluate operations ! and
122 !!. ! g_eform evaluates g_form and the value is
123 inserted in the place of the call; !! l_form
124 evaluates l_form and the value is spliced into
125 the place of the call.
126
127
128 Printed: January 31, 1984
129
130
131
132
133
134
135
136Data Structure Access 2-3
137
138
139 `Splicing in' means that the parentheses sur-
140 rounding the list are removed as the example
141 below shows. Use of the evaluate operators can
142 occur at any level in a form argument.
143
144 Another way to get the effect of the _\bq_\bu_\bo_\bt_\be! func-
145 tion is to use the backquote character macro (see
146 8.3.3).
147
148
149 ____________________________________________________
150
151 (_\bq_\bu_\bo_\bt_\be! _\bc_\bo_\bn_\bs ! (_\bc_\bo_\bn_\bs _\b1 _\b2) _\b3) = (_\bc_\bo_\bn_\bs (_\b1 . _\b2) _\b3)
152 (_\bq_\bu_\bo_\bt_\be! _\b1 !! (_\bl_\bi_\bs_\bt _\b2 _\b3 _\b4) _\b5) = (_\b1 _\b2 _\b3 _\b4 _\b5)
153 (_\bs_\be_\bt_\bq _\bq_\bu_\bo_\bt_\be_\bd '_\be_\bv_\ba_\bl_\be_\bd)(_\bq_\bu_\bo_\bt_\be! ! ((_\bI _\ba_\bm ! _\bq_\bu_\bo_\bt_\be_\bd))) = ((_\bI _\ba_\bm _\be_\bv_\ba_\bl_\be_\bd))
154 (_\bq_\bu_\bo_\bt_\be! _\bt_\br_\by ! '(_\bt_\bh_\bi_\bs ! _\bo_\bn_\be)) = (_\bt_\br_\by (_\bt_\bh_\bi_\bs ! _\bo_\bn_\be))
155 ____________________________________________________
156
157
158
159
160
161(bignum-to-list 'b_arg)
162
163 RETURNS: A list of the fixnums which are used to
164 represent the bignum.
165
166 NOTE: the inverse of this function is _\bl_\bi_\bs_\bt-_\bt_\bo-_\bb_\bi_\bg_\bn_\bu_\bm.
167
168(list-to-bignum 'l_ints)
169
170 WHERE: l_ints is a list of fixnums.
171
172 RETURNS: a bignum constructed of the given fixnums.
173
174 NOTE: the inverse of this function is _\bb_\bi_\bg_\bn_\bu_\bm-_\bt_\bo-_\bl_\bi_\bs_\bt.
175
176
177
178
179 2.1.2. list predicates
180
181
182
183
184
185
186
187
188
189
190
191\e9
192
193\e9 Printed: January 31, 1984
194
195
196
197
198
199
200
201Data Structure Access 2-4
202
203
204(dtpr 'g_arg)
205
206 RETURNS: t iff g_arg is a list cell.
207
208 NOTE: that (dtpr '()) is nil. The name dtpr is a con-
209 traction for ``dotted pair''.
210
211(listp 'g_arg)
212
213 RETURNS: t iff g_arg is a list object or nil.
214
215(tailp 'l_x 'l_y)
216
217 RETURNS: l_x, if a list cell _\be_\bq to l_x is found by
218 _\bc_\bd_\bring down l_y zero or more times, nil other-
219 wise.
220
221
222 ____________________________________________________
223
224 -> (_\bs_\be_\bt_\bq _\bx '(_\ba _\bb _\bc _\bd) _\by (_\bc_\bd_\bd_\br _\bx))
225 (c d)
226 -> (_\ba_\bn_\bd (_\bd_\bt_\bp_\br _\bx) (_\bl_\bi_\bs_\bt_\bp _\bx)) ; x and y are dtprs and lists
227 t
228 -> (_\bd_\bt_\bp_\br '()) ; () is the same as nil and is not a dtpr
229 nil
230 -> (_\bl_\bi_\bs_\bt_\bp '()) ; however it is a list
231 t
232 -> (_\bt_\ba_\bi_\bl_\bp _\by _\bx)
233 (c d)
234 ____________________________________________________
235
236
237
238
239(length 'l_arg)
240
241 RETURNS: the number of elements in the top level of
242 list l_arg.
243
244
245
246 2.1.3. list accessing
247
248
249
250
251
252
253
254
255
256\e9
257
258\e9 Printed: January 31, 1984
259
260
261
262
263
264
265
266Data Structure Access 2-5
267
268
269(car 'l_arg)
270(cdr 'l_arg)
271
272 RETURNS: _\bc_\bo_\bn_\bs cell. (_\bc_\ba_\br (_\bc_\bo_\bn_\bs x y)) is always x, (_\bc_\bd_\br
273 (_\bc_\bo_\bn_\bs x y)) is always y. In FRANZ LISP, the
274 cdr portion is located first in memory. This
275 is hardly noticeable, and we mention it pri-
276 marily as a curiosity.
277
278(c..r 'lh_arg)
279
280 WHERE: the .. represents any positive number of a's
281 and d's.
282
283 RETURNS: the result of accessing the list structure in
284 the way determined by the function name. The
285 a's and d's are read from right to left, a d
286 directing the access down the cdr part of the
287 list cell and an a down the car part.
288
289 NOTE: lh_arg may also be nil, and it is guaranteed that
290 the car and cdr of nil is nil. If lh_arg is a
291 hunk, then (_\bc_\ba_\br '_\bl_\bh__\ba_\br_\bg) is the same as
292 (_\bc_\bx_\br _\b1 '_\bl_\bh__\ba_\br_\bg) and (_\bc_\bd_\br '_\bl_\bh__\ba_\br_\bg) is the same as
293 (_\bc_\bx_\br _\b0 '_\bl_\bh__\ba_\br_\bg).
294 It is generally hard to read and understand the
295 context of functions with large strings of a's
296 and d's, but these functions are supported by
297 rapid accessing and open-compiling (see Chapter
298 12).
299
300(nth 'x_index 'l_list)
301
302 RETURNS: the nth element of l_list, assuming zero-based
303 index. Thus (nth 0 l_list) is the same as
304 (car l_list). _\bn_\bt_\bh is both a function, and a
305 compiler macro, so that more efficient code
306 might be generated than for _\bn_\bt_\bh_\be_\bl_\be_\bm (described
307 below).
308
309 NOTE: If x_arg1 is non-positive or greater than the
310 length of the list, nil is returned.
311
312
313
314
315
316
317
318
319
320
321\e9
322
323\e9 Printed: January 31, 1984
324
325
326
327
328
329
330
331Data Structure Access 2-6
332
333
334(nthcdr 'x_index 'l_list)
335
336 RETURNS: the result of _\bc_\bd_\bring down the list l_list
337 x_index times.
338
339 NOTE: If x_index is less than 0, then
340 (_\bc_\bo_\bn_\bs _\bn_\bi_\bl '_\bl__\bl_\bi_\bs_\bt) is returned.
341
342(nthelem 'x_arg1 'l_arg2)
343
344 RETURNS: The x_arg1'_\bs_\bt element of the list l_arg2.
345
346 NOTE: This function comes from the PDP-11 Lisp system.
347
348(last 'l_arg)
349
350 RETURNS: the last list cell in the list l_arg.
351
352 EXAMPLE: _\bl_\ba_\bs_\bt does NOT return the last element of a
353 list!
354 (_\bl_\ba_\bs_\bt '(_\ba _\bb)) = (b)
355
356(ldiff 'l_x 'l_y)
357
358 RETURNS: a list of all elements in l_x but not in l_y
359 , i.e., the list difference of l_x and l_y.
360
361 NOTE: l_y must be a tail of l_x, i.e., _\be_\bq to the result
362 of applying some number of _\bc_\bd_\br's to l_x. Note
363 that the value of _\bl_\bd_\bi_\bf_\bf is always new
364 list structure unless l_y is nil, in which case
365 (_\bl_\bd_\bi_\bf_\bf _\bl__\bx _\bn_\bi_\bl) is l_x itself. If l_y is not
366 a tail of l_x, _\bl_\bd_\bi_\bf_\bf generates an error.
367
368 EXAMPLE: (_\bl_\bd_\bi_\bf_\bf '_\bl__\bx (_\bm_\be_\bm_\bb_\be_\br '_\bg__\bf_\bo_\bo '_\bl__\bx)) gives all
369 elements in l_x up to the first g_foo.
370
371
372
373 2.1.4. list manipulation
374
375(rplaca 'lh_arg1 'g_arg2)
376
377 RETURNS: the modified lh_arg1.
378
379 SIDE EFFECT: the car of lh_arg1 is set to g_arg2. If
380 lh_arg1 is a hunk then the second element
381 of the hunk is set to g_arg2.
382
383
384
385
386\e9
387
388\e9 Printed: January 31, 1984
389
390
391
392
393
394
395
396Data Structure Access 2-7
397
398
399(rplacd 'lh_arg1 'g_arg2)
400
401 RETURNS: the modified lh_arg1.
402
403 SIDE EFFECT: the cdr of lh_arg2 is set to g_arg2. If
404 lh_arg1 is a hunk then the first element
405 of the hunk is set to g_arg2.
406
407
408(attach 'g_x 'l_l)
409
410 RETURNS: l_l whose _\bc_\ba_\br is now g_x, whose _\bc_\ba_\bd_\br is the
411 original (_\bc_\ba_\br _\bl__\bl), and whose _\bc_\bd_\bd_\br is the ori-
412 ginal (_\bc_\bd_\br _\bl__\bl).
413
414 NOTE: what happens is that g_x is added to the begin-
415 ning of list l_l yet maintaining the same list
416 cell at the beginning of the list.
417
418(delete 'g_val 'l_list ['x_count])
419
420 RETURNS: the result of splicing g_val from the top
421 level of l_list no more than x_count times.
422
423 NOTE: x_count defaults to a very large number, thus if
424 x_count is not given, all occurrences of g_val
425 are removed from the top level of l_list. g_val
426 is compared with successive _\bc_\ba_\br's of l_list using
427 the function _\be_\bq_\bu_\ba_\bl.
428
429 SIDE EFFECT: l_list is modified using rplacd, no new
430 list cells are used.
431
432(delq 'g_val 'l_list ['x_count])
433(dremove 'g_val 'l_list ['x_count])
434
435 RETURNS: the result of splicing g_val from the top
436 level of l_list no more than x_count times.
437
438 NOTE: _\bd_\be_\bl_\bq (and _\bd_\br_\be_\bm_\bo_\bv_\be) are the same as _\bd_\be_\bl_\be_\bt_\be except
439 that _\be_\bq is used for comparison instead of _\be_\bq_\bu_\ba_\bl.
440
441
442
443
444
445
446
447
448
449
450
451\e9
452
453\e9 Printed: January 31, 1984
454
455
456
457
458
459
460
461Data Structure Access 2-8
462
463
464
465 ____________________________________________________
466
467 ; note that you should use the value returned by _\bd_\be_\bl_\be_\bt_\be or _\bd_\be_\bl_\bq
468 ; and not assume that g_val will always show the deletions.
469 ; For example
470
471 -> (_\bs_\be_\bt_\bq _\bt_\be_\bs_\bt '(_\ba _\bb _\bc _\ba _\bd _\be))
472 (a b c a d e)
473 -> (_\bd_\be_\bl_\be_\bt_\be '_\ba _\bt_\be_\bs_\bt)
474 (b c d e) ; the value returned is what we would expect
475 -> _\bt_\be_\bs_\bt
476 (a b c d e) ; but test still has the first a in the list!
477 ____________________________________________________
478
479
480
481
482(remq 'g_x 'l_l ['x_count])
483(remove 'g_x 'l_l)
484
485 RETURNS: a _\bc_\bo_\bp_\by of l_l with all top level elements
486 _\be_\bq_\bu_\ba_\bl to g_x removed. _\br_\be_\bm_\bq uses _\be_\bq instead of
487 _\be_\bq_\bu_\ba_\bl for comparisons.
488
489 NOTE: remove does not modify its arguments like _\bd_\be_\bl_\be_\bt_\be,
490 and _\bd_\be_\bl_\bq do.
491
492(insert 'g_object 'l_list 'u_comparefn 'g_nodups)
493
494 RETURNS: a list consisting of l_list with g_object des-
495 tructively inserted in a place determined by
496 the ordering function u_comparefn.
497
498 NOTE: (_\bc_\bo_\bm_\bp_\ba_\br_\be_\bf_\bn '_\bg__\bx '_\bg__\by) should return something
499 non-nil if g_x can precede g_y in sorted order,
500 nil if g_y must precede g_x. If u_comparefn is
501 nil, alphabetical order will be used. If g_nodups
502 is non-nil, an element will not be inserted if an
503 equal element is already in the list. _\bi_\bn_\bs_\be_\br_\bt
504 does binary search to determine where to insert
505 the new element.
506
507
508
509
510
511
512
513
514
515
516\e9
517
518\e9 Printed: January 31, 1984
519
520
521
522
523
524
525
526Data Structure Access 2-9
527
528
529(merge 'l_data1 'l_data2 'u_comparefn)
530
531 RETURNS: the merged list of the two input sorted lists
532 l_data1 and l_data1 using binary comparison
533 function u_comparefn.
534
535 NOTE: (_\bc_\bo_\bm_\bp_\ba_\br_\be_\bf_\bn '_\bg__\bx '_\bg__\by) should return something
536 non-nil if g_x can precede g_y in sorted order,
537 nil if g_y must precede g_x. If u_comparefn is
538 nil, alphabetical order will be used.
539 u_comparefn should be thought of as "less than or
540 equal". _\bm_\be_\br_\bg_\be changes both of its data argu-
541 ments.
542
543(subst 'g_x 'g_y 'l_s)
544(dsubst 'g_x 'g_y 'l_s)
545
546 RETURNS: the result of substituting g_x for all _\be_\bq_\bu_\ba_\bl
547 occurrences of g_y at all levels in l_s.
548
549 NOTE: If g_y is a symbol, _\be_\bq will be used for comparis-
550 ons. The function _\bs_\bu_\bb_\bs_\bt does not modify l_s but
551 the function _\bd_\bs_\bu_\bb_\bs_\bt (destructive substitution)
552 does.
553
554(lsubst 'l_x 'g_y 'l_s)
555
556 RETURNS: a copy of l_s with l_x spliced in for every
557 occurrence of of g_y at all levels. Splicing
558 in means that the parentheses surrounding the
559 list l_x are removed as the example below
560 shows.
561
562
563 ____________________________________________________
564
565 -> (_\bs_\bu_\bb_\bs_\bt '(_\ba _\bb _\bc) '_\bx '(_\bx _\by _\bz (_\bx _\by _\bz) (_\bx _\by _\bz)))
566 ((a b c) y z ((a b c) y z) ((a b c) y z))
567 -> (_\bl_\bs_\bu_\bb_\bs_\bt '(_\ba _\bb _\bc) '_\bx '(_\bx _\by _\bz (_\bx _\by _\bz) (_\bx _\by _\bz)))
568 (a b c y z (a b c y z) (a b c y z))
569 ____________________________________________________
570
571
572
573
574
575
576
577
578
579
580
581\e9
582
583\e9 Printed: January 31, 1984
584
585
586
587
588
589
590
591Data Structure Access 2-10
592
593
594(subpair 'l_old 'l_new 'l_expr)
595
596 WHERE: there are the same number of elements in
597 l_old as l_new.
598
599 RETURNS: the list l_expr with all occurrences of a
600 object in l_old replaced by the corresponding
601 one in l_new. When a substitution is made, a
602 copy of the value to substitute in is not
603 made.
604
605 EXAMPLE: (_\bs_\bu_\bb_\bp_\ba_\bi_\br '(_\ba _\bc)' (_\bx _\by) '(_\ba _\bb _\bc _\bd)) = (_\bx _\bb _\by _\bd)
606
607
608(nconc 'l_arg1 'l_arg2 ['l_arg3 ...])
609
610 RETURNS: A list consisting of the elements of l_arg1
611 followed by the elements of l_arg2 followed by
612 l_arg3 and so on.
613
614 NOTE: The _\bc_\bd_\br of the last list cell of l_arg_\bi is
615 changed to point to l_arg_\bi+_\b1.
616
617
618 ____________________________________________________
619
620 ; _\bn_\bc_\bo_\bn_\bc is faster than _\ba_\bp_\bp_\be_\bn_\bd because it doesn't allocate new list cells.
621 -> (_\bs_\be_\bt_\bq _\bl_\bi_\bs_\b1 '(_\ba _\bb _\bc))
622 (a b c)
623 -> (_\bs_\be_\bt_\bq _\bl_\bi_\bs_\b2 '(_\bd _\be _\bf))
624 (d e f)
625 -> (_\ba_\bp_\bp_\be_\bn_\bd _\bl_\bi_\bs_\b1 _\bl_\bi_\bs_\b2)
626 (a b c d e f)
627 -> _\bl_\bi_\bs_\b1
628 (a b c) ; note that lis1 has not been changed by _\ba_\bp_\bp_\be_\bn_\bd
629 -> (_\bn_\bc_\bo_\bn_\bc _\bl_\bi_\bs_\b1 _\bl_\bi_\bs_\b2)
630 (a b c d e f) ; _\bn_\bc_\bo_\bn_\bc returns the same value as _\ba_\bp_\bp_\be_\bn_\bd
631 -> _\bl_\bi_\bs_\b1
632 (a b c d e f) ; but in doing so alters lis1
633 ____________________________________________________
634
635
636
637
638
639
640
641
642
643
644
645
646\e9
647
648\e9 Printed: January 31, 1984
649
650
651
652
653
654
655
656Data Structure Access 2-11
657
658
659(reverse 'l_arg)
660(nreverse 'l_arg)
661
662 RETURNS: the list l_arg with the elements at the top
663 level in reverse order.
664
665 NOTE: The function _\bn_\br_\be_\bv_\be_\br_\bs_\be does the reversal in place,
666 that is the list structure is modified.
667
668(nreconc 'l_arg 'g_arg)
669
670 EQUIVALENT TO: (_\bn_\bc_\bo_\bn_\bc (_\bn_\br_\be_\bv_\be_\br_\bs_\be '_\bl__\ba_\br_\bg) '_\bg__\ba_\br_\bg)
671
672
673
674
675 2.2. Predicates
676
677 The following functions test for properties of
678 data objects. When the result of the test is either
679 'false' or 'true', then nil will be returned for
680 'false' and something other than nil (often t) will be
681 returned for 'true'.
682
683(arrayp 'g_arg)
684
685 RETURNS: t iff g_arg is of type array.
686
687(atom 'g_arg)
688
689 RETURNS: t iff g_arg is not a list or hunk object.
690
691 NOTE: (_\ba_\bt_\bo_\bm '()) returns t.
692
693(bcdp 'g_arg)
694
695 RETURNS: t iff g_arg is a data object of type binary.
696
697 NOTE: This function is a throwback to the PDP-11 Lisp
698 system. The name stands for binary code predi-
699 cate.
700
701
702
703
704
705
706
707
708
709
710
711\e9
712
713\e9 Printed: January 31, 1984
714
715
716
717
718
719
720
721Data Structure Access 2-12
722
723
724(bigp 'g_arg)
725
726 RETURNS: t iff g_arg is a bignum.
727
728(dtpr 'g_arg)
729
730 RETURNS: t iff g_arg is a list cell.
731
732 NOTE: that (dtpr '()) is nil.
733
734(hunkp 'g_arg)
735
736 RETURNS: t iff g_arg is a hunk.
737
738(listp 'g_arg)
739
740 RETURNS: t iff g_arg is a list object or nil.
741
742(stringp 'g_arg)
743
744 RETURNS: t iff g_arg is a string.
745
746(symbolp 'g_arg)
747
748 RETURNS: t iff g_arg is a symbol.
749
750(valuep 'g_arg)
751
752 RETURNS: t iff g_arg is a value cell
753
754(vectorp 'v_vector)
755
756 RETURNS: t iff the argument is a vector.
757
758(vectorip 'v_vector)
759
760 RETURNS: t iff the argument is an immediate-vector.
761
762(type 'g_arg)
763(typep 'g_arg)
764
765 RETURNS: a symbol whose pname describes the type of
766 g_arg.
767
768
769
770
771
772
773
774
775
776\e9
777
778\e9 Printed: January 31, 1984
779
780
781
782
783
784
785
786Data Structure Access 2-13
787
788
789(signp s_test 'g_val)
790
791 RETURNS: t iff g_val is a number and the given test
792 s_test on g_val returns true.
793
794 NOTE: The fact that _\bs_\bi_\bg_\bn_\bp simply returns nil if g_val
795 is not a number is probably the most important
796 reason that _\bs_\bi_\bg_\bn_\bp is used. The permitted values
797 for s_test and what they mean are given in this
798 table.
799
800\e8 ____________________
801 s_test tested
802
803\e8 ____________________\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b____________________
804 l g_val < 0
805 le g_val <\b_ 0
806 e g_val = 0
807 n g_val =\b/ 0
808 ge g_val >\b_ 0
809 g g_val > 0
810\e8 ____________________
811\e7 |\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
812
813
814
815
816
817
818
819 |\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
820
821
822
823
824
825
826
827
828
829
830(eq 'g_arg1 'g_arg2)
831
832 RETURNS: t if g_arg1 and g_arg2 are the exact same lisp
833 object.
834
835 NOTE: _\bE_\bq simply tests if g_arg1 and g_arg2 are located
836 in the exact same place in memory. Lisp objects
837 which print the same are not necessarily _\be_\bq. The
838 only objects guaranteed to be _\be_\bq are interned
839 symbols with the same print name. [Unless a sym-
840 bol is created in a special way (such as with
841 _\bu_\bc_\bo_\bn_\bc_\ba_\bt or _\bm_\ba_\bk_\bn_\ba_\bm) it will be interned.]
842
843(neq 'g_x 'g_y)
844
845 RETURNS: t if g_x is not _\be_\bq to g_y, otherwise nil.
846
847(equal 'g_arg1 'g_arg2)
848(eqstr 'g_arg1 'g_arg2)
849
850 RETURNS: t iff g_arg1 and g_arg2 have the same struc-
851 ture as described below.
852
853 NOTE: g_arg and g_arg2 are _\be_\bq_\bu_\ba_\bl if
854
855 (1) they are _\be_\bq.
856
857 (2) they are both fixnums with the same value
858
859
860
861
862\e9 Printed: January 31, 1984
863
864
865
866
867
868
869
870Data Structure Access 2-14
871
872
873 (3) they are both flonums with the same value
874
875 (4) they are both bignums with the same value
876
877 (5) they are both strings and are identical.
878
879 (6) they are both lists and their cars and cdrs are
880 _\be_\bq_\bu_\ba_\bl.
881
882
883 ____________________________________________________
884
885 ; _\be_\bq is much faster than _\be_\bq_\bu_\ba_\bl, especially in compiled code,
886 ; however you cannot use _\be_\bq to test for equality of numbers outside
887 ; of the range -1024 to 1023. _\be_\bq_\bu_\ba_\bl will always work.
888 -> (_\be_\bq _\b1_\b0_\b2_\b3 _\b1_\b0_\b2_\b3)
889 t
890 -> (_\be_\bq _\b1_\b0_\b2_\b4 _\b1_\b0_\b2_\b4)
891 nil
892 -> (_\be_\bq_\bu_\ba_\bl _\b1_\b0_\b2_\b4 _\b1_\b0_\b2_\b4)
893 t
894 ____________________________________________________
895
896
897
898
899
900(not 'g_arg)
901(null 'g_arg)
902
903 RETURNS: t iff g_arg is nil.
904
905
906(member 'g_arg1 'l_arg2)
907(memq 'g_arg1 'l_arg2)
908
909 RETURNS: that part of the l_arg2 beginning with the
910 first occurrence of g_arg1. If g_arg1 is not
911 in the top level of l_arg2, nil is returned.
912
913 NOTE: _\bm_\be_\bm_\bb_\be_\br tests for equality with _\be_\bq_\bu_\ba_\bl, _\bm_\be_\bm_\bq tests
914 for equality with _\be_\bq.
915
916
917
918
919 2.3. Symbols and Strings
920
921 In many of the following functions the distinc-
922 tion between symbols and strings is somewhat blurred.
923 To remind ourselves of the difference, a string is a
924 null terminated sequence of characters, stored as com-
925 pactly as possible. Strings are used as constants in
926
927
928 Printed: January 31, 1984
929
930
931
932
933
934
935
936Data Structure Access 2-15
937
938
939 FRANZ LISP. They _\be_\bv_\ba_\bl to themselves. A symbol has
940 additional structure: a value, property list, function
941 binding, as well as its external representation (or
942 print-name). If a symbol is given to one of the
943 string manipulation functions below, its print name
944 will be used as the string.
945
946 Another popular way to represent strings in Lisp
947 is as a list of fixnums which represent characters.
948 The suffix 'n' to a string manipulation function indi-
949 cates that it returns a string in this form.
950
951
952
953 2.3.1. symbol and string creation
954
955(concat ['stn_arg1 ... ])
956(uconcat ['stn_arg1 ... ])
957
958 RETURNS: a symbol whose print name is the result of
959 concatenating the print names, string charac-
960 ters or numerical representations of the
961 sn_arg_\bi.
962
963 NOTE: If no arguments are given, a symbol with a null
964 pname is returned. _\bc_\bo_\bn_\bc_\ba_\bt places the symbol
965 created on the oblist, the function _\bu_\bc_\bo_\bn_\bc_\ba_\bt does
966 the same thing but does not place the new symbol
967 on the oblist.
968
969 EXAMPLE: (_\bc_\bo_\bn_\bc_\ba_\bt '_\ba_\bb_\bc (_\ba_\bd_\bd _\b3 _\b4) "_\bd_\be_\bf") = abc7def
970
971(concatl 'l_arg)
972
973 EQUIVALENT TO: (_\ba_\bp_\bp_\bl_\by '_\bc_\bo_\bn_\bc_\ba_\bt '_\bl__\ba_\br_\bg)
974
975
976(implode 'l_arg)
977(maknam 'l_arg)
978
979 WHERE: l_arg is a list of symbols, strings and small
980 fixnums.
981
982 RETURNS: The symbol whose print name is the result of
983 concatenating the first characters of the
984 print names of the symbols and strings in the
985 list. Any fixnums are converted to the
986 equivalent ascii character. In order to con-
987 catenate entire strings or print names, use
988 the function _\bc_\bo_\bn_\bc_\ba_\bt.
989
990 NOTE: _\bi_\bm_\bp_\bl_\bo_\bd_\be interns the symbol it creates, _\bm_\ba_\bk_\bn_\ba_\bm
991 does not.
992
993
994 Printed: January 31, 1984
995
996
997
998
999
1000
1001
1002Data Structure Access 2-16
1003
1004
1005(gensym ['s_leader])
1006
1007 RETURNS: a new uninterned atom beginning with the first
1008 character of s_leader's pname, or beginning
1009 with g if s_leader is not given.
1010
1011 NOTE: The symbol looks like x0nnnnn where x is
1012 s_leader's first character and nnnnn is the
1013 number of times you have called gensym.
1014
1015(copysymbol 's_arg 'g_pred)
1016
1017 RETURNS: an uninterned symbol with the same print name
1018 as s_arg. If g_pred is non nil, then the
1019 value, function binding and property list of
1020 the new symbol are made _\be_\bq to those of s_arg.
1021
1022
1023(ascii 'x_charnum)
1024
1025 WHERE: x_charnum is between 0 and 255.
1026
1027 RETURNS: a symbol whose print name is the single char-
1028 acter whose fixnum representation is
1029 x_charnum.
1030
1031
1032(intern 's_arg)
1033
1034 RETURNS: s_arg
1035
1036 SIDE EFFECT: s_arg is put on the oblist if it is not
1037 already there.
1038
1039(remob 's_symbol)
1040
1041 RETURNS: s_symbol
1042
1043 SIDE EFFECT: s_symbol is removed from the oblist.
1044
1045(rematom 's_arg)
1046
1047 RETURNS: t if s_arg is indeed an atom.
1048
1049 SIDE EFFECT: s_arg is put on the free atoms list,
1050 effectively reclaiming an atom cell.
1051
1052 NOTE: This function does _\bn_\bo_\bt check to see if s_arg is
1053 on the oblist or is referenced anywhere. Thus
1054 calling _\br_\be_\bm_\ba_\bt_\bo_\bm on an atom in the oblist may
1055 result in disaster when that atom cell is reused!
1056
1057\e9
1058
1059\e9 Printed: January 31, 1984
1060
1061
1062
1063
1064
1065
1066
1067Data Structure Access 2-17
1068
1069
1070 2.3.2. string and symbol predicates
1071
1072(boundp 's_name)
1073
1074 RETURNS: nil if s_name is unbound: that is, it has
1075 never been given a value. If x_name has the
1076 value g_val, then (nil . g_val) is returned.
1077 See also _\bm_\ba_\bk_\bu_\bn_\bb_\bo_\bu_\bn_\bd.
1078
1079(alphalessp 'st_arg1 'st_arg2)
1080
1081 RETURNS: t iff the `name' of st_arg1 is alphabetically
1082 less than the name of st_arg2. If st_arg is a
1083 symbol then its `name' is its print name. If
1084 st_arg is a string, then its `name' is the
1085 string itself.
1086
1087
1088
1089 2.3.3. symbol and string accessing
1090
1091(symeval 's_arg)
1092
1093 RETURNS: the value of symbol s_arg.
1094
1095 NOTE: It is illegal to ask for the value of an unbound
1096 symbol. This function has the same effect as
1097 _\be_\bv_\ba_\bl, but compiles into much more efficient code.
1098
1099(get_pname 's_arg)
1100
1101 RETURNS: the string which is the print name of s_arg.
1102
1103(plist 's_arg)
1104
1105 RETURNS: the property list of s_arg.
1106
1107(getd 's_arg)
1108
1109 RETURNS: the function definition of s_arg or nil if
1110 there is no function definition.
1111
1112 NOTE: the function definition may turn out to be an
1113 array header.
1114
1115
1116
1117
1118
1119
1120
1121
1122\e9
1123
1124\e9 Printed: January 31, 1984
1125
1126
1127
1128
1129
1130
1131
1132Data Structure Access 2-18
1133
1134
1135(getchar 's_arg 'x_index)
1136(nthchar 's_arg 'x_index)
1137(getcharn 's_arg 'x_index)
1138
1139 RETURNS: the x_index_\bt_\bh character of the print name of
1140 s_arg or nil if x_index is less than 1 or
1141 greater than the length of s_arg's print name.
1142
1143 NOTE: _\bg_\be_\bt_\bc_\bh_\ba_\br and _\bn_\bt_\bh_\bc_\bh_\ba_\br return a symbol with a single
1144 character print name, _\bg_\be_\bt_\bc_\bh_\ba_\br_\bn returns the fixnum
1145 representation of the character.
1146
1147(substring 'st_string 'x_index ['x_length])
1148(substringn 'st_string 'x_index ['x_length])
1149
1150 RETURNS: a string of length at most x_length starting
1151 at x_index_\bt_\bh character in the string.
1152
1153 NOTE: If x_length is not given, all of the characters
1154 for x_index to the end of the string are
1155 returned. If x_index is negative the string
1156 begins at the x_index_\bt_\bh character from the end.
1157 If x_index is out of bounds, nil is returned.
1158
1159 NOTE: _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg returns a list of symbols, _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg_\bn
1160 returns a list of fixnums. If _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg_\bn is
1161 given a 0 x_length argument then a single fixnum
1162 which is the x_index_\bt_\bh character is returned.
1163
1164
1165
1166 2.3.4. symbol and string manipulation
1167
1168(set 's_arg1 'g_arg2)
1169
1170 RETURNS: g_arg2.
1171
1172 SIDE EFFECT: the value of s_arg1 is set to g_arg2.
1173
1174(setq s_atm1 'g_val1 [ s_atm2 'g_val2 ... ... ])
1175
1176 WHERE: the arguments are pairs of atom names and
1177 expressions.
1178
1179 RETURNS: the last g_val_\bi.
1180
1181 SIDE EFFECT: each s_atm_\bi is set to have the value
1182 g_val_\bi.
1183
1184 NOTE: _\bs_\be_\bt evaluates all of its arguments, _\bs_\be_\bt_\bq does not
1185 evaluate the s_atm_\bi.
1186
1187\e9
1188
1189\e9 Printed: January 31, 1984
1190
1191
1192
1193
1194
1195
1196
1197Data Structure Access 2-19
1198
1199
1200(desetq sl_pattern1 'g_exp1 [... ...])
1201
1202 RETURNS: g_expn
1203
1204 SIDE EFFECT: This acts just like _\bs_\be_\bt_\bq if all the
1205 sl_pattern_\bi are symbols. If sl_pattern_\bi
1206 is a list then it is a template which
1207 should have the same structure as g_exp_\bi
1208 The symbols in sl_pattern are assigned to
1209 the corresponding parts of g_exp. (See
1210 also _\bs_\be_\bt_\bf )
1211
1212 EXAMPLE: (_\bd_\be_\bs_\be_\bt_\bq (_\ba _\bb (_\bc . _\bd)) '(_\b1 _\b2 (_\b3 _\b4 _\b5)))
1213 sets a to 1, b to 2, c to 3, and d to (4 5).
1214
1215
1216(setplist 's_atm 'l_plist)
1217
1218 RETURNS: l_plist.
1219
1220 SIDE EFFECT: the property list of s_atm is set to
1221 l_plist.
1222
1223(makunbound 's_arg)
1224
1225 RETURNS: s_arg
1226
1227 SIDE EFFECT: the value of s_arg is made `unbound'. If
1228 the interpreter attempts to evaluate s_arg
1229 before it is again given a value, an
1230 unbound variable error will occur.
1231
1232(aexplode 's_arg)
1233(explode 'g_arg)
1234(aexplodec 's_arg)
1235(explodec 'g_arg)
1236(aexploden 's_arg)
1237(exploden 'g_arg)
1238
1239 RETURNS: a list of the characters used to print out
1240 s_arg or g_arg.
1241
1242 NOTE: The functions beginning with 'a' are internal
1243 functions which are limited to symbol arguments.
1244 The functions _\ba_\be_\bx_\bp_\bl_\bo_\bd_\be and _\be_\bx_\bp_\bl_\bo_\bd_\be return a list
1245 of characters which _\bp_\br_\bi_\bn_\bt would use to print the
1246 argument. These characters include all necessary
1247 escape characters. Functions _\ba_\be_\bx_\bp_\bl_\bo_\bd_\be_\bc and
1248 _\be_\bx_\bp_\bl_\bo_\bd_\be_\bc return a list of characters which _\bp_\ba_\bt_\bo_\bm
1249 would use to print the argument (i.e. no escape
1250 characters). Functions _\ba_\be_\bx_\bp_\bl_\bo_\bd_\be_\bn and _\be_\bx_\bp_\bl_\bo_\bd_\be_\bn
1251 are similar to _\ba_\be_\bx_\bp_\bl_\bo_\bd_\be_\bc and _\be_\bx_\bp_\bl_\bo_\bd_\be_\bc except that
1252 a list of fixnum equivalents of characters are
1253
1254
1255 Printed: January 31, 1984
1256
1257
1258
1259
1260
1261
1262
1263Data Structure Access 2-20
1264
1265
1266 returned.
1267
1268
1269 ____________________________________________________
1270
1271 -> (_\bs_\be_\bt_\bq _\bx '|_\bq_\bu_\bo_\bt_\be _\bt_\bh_\bi_\bs _\b\| _\bo_\bk?|)
1272 |quote this \| ok?|
1273 -> (_\be_\bx_\bp_\bl_\bo_\bd_\be _\bx)
1274 (q u o t e |\\| | | t h i s |\\| | | |\\| |\|| |\\| | | o k ?)
1275 ; note that |\\| just means the single character: backslash.
1276 ; and |\|| just means the single character: vertical bar
1277 ; and | | means the single character: space
1278
1279 -> (_\be_\bx_\bp_\bl_\bo_\bd_\be_\bc _\bx)
1280 (q u o t e | | t h i s | | |\|| | | o k ?)
1281 -> (_\be_\bx_\bp_\bl_\bo_\bd_\be_\bn _\bx)
1282 (113 117 111 116 101 32 116 104 105 115 32 124 32 111 107 63)
1283 ____________________________________________________
1284
1285
1286
1287
1288
1289
1290 2.4. Vectors
1291
1292 See Chapter 9 for a discussion of vectors. They
1293 are less efficient that hunks but more efficient than
1294 arrays.
1295
1296
1297
1298 2.4.1. vector creation
1299
1300(new-vector 'x_size ['g_fill ['g_prop]])
1301
1302 RETURNS: A vector of length x_size. Each data entry is
1303 initialized to g_fill, or to nil, if the argu-
1304 ment g_fill is not present. The vector's pro-
1305 perty is set to g_prop, or to nil, by default.
1306
1307(new-vectori-byte 'x_size ['g_fill ['g_prop]])
1308(new-vectori-word 'x_size ['g_fill ['g_prop]])
1309(new-vectori-long 'x_size ['g_fill ['g_prop]])
1310
1311 RETURNS: A vectori with x_size elements in it. The
1312 actual memory requirement is two long words +
1313 x_size*(n bytes), where n is 1 for new-
1314 vector-byte, 2 for new-vector-word, or 4 for
1315 new-vectori-long. Each data entry is initial-
1316 ized to g_fill, or to zero, if the argument
1317 g_fill is not present. The vector's property
1318 is set to g_prop, or nil, by default.
1319
1320
1321 Printed: January 31, 1984
1322
1323
1324
1325
1326
1327
1328
1329Data Structure Access 2-21
1330
1331
1332 Vectors may be created by specifying multiple initial
1333 values:
1334
1335(vector ['g_val0 'g_val1 ...])
1336
1337 RETURNS: a vector, with as many data elements as there
1338 are arguments. It is quite possible to have a
1339 vector with no data elements. The vector's
1340 property will be a null list.
1341
1342(vectori-byte ['x_val0 'x_val2 ...])
1343(vectori-word ['x_val0 'x_val2 ...])
1344(vectori-long ['x_val0 'x_val2 ...])
1345
1346 RETURNS: a vectori, with as many data elements as there
1347 are arguments. The arguments are required to
1348 be fixnums. Only the low order byte or word
1349 is used in the case of vectori-byte and
1350 vectori-word. The vector's property will be
1351 null.
1352
1353
1354
1355 2.4.2. vector reference
1356
1357(vref 'v_vect 'x_index)
1358(vrefi-byte 'V_vect 'x_bindex)
1359(vrefi-word 'V_vect 'x_windex)
1360(vrefi-long 'V_vect 'x_lindex)
1361
1362 RETURNS: the desired data element from a vector. The
1363 indices must be fixnums. Indexing is zero-
1364 based. The vrefi functions sign extend the
1365 data.
1366
1367(vprop 'Vv_vect)
1368
1369 RETURNS: The Lisp property associated with a vector.
1370
1371(vget 'Vv_vect 'g_ind)
1372
1373 RETURNS: The value stored under g_ind if the Lisp pro-
1374 perty associated with 'Vv_vect is a disembo-
1375 died property list.
1376
1377
1378
1379
1380
1381
1382
1383
1384\e9
1385
1386\e9 Printed: January 31, 1984
1387
1388
1389
1390
1391
1392
1393
1394Data Structure Access 2-22
1395
1396
1397(vsize 'Vv_vect)
1398(vsize-byte 'V_vect)
1399(vsize-word 'V_vect)
1400
1401 RETURNS: the number of data elements in the vector.
1402 For immediate-vectors, the functions vsize-
1403 byte and vsize-word return the number of data
1404 elements, if one thinks of the binary data as
1405 being comprised of bytes or words.
1406
1407
1408
1409 2.4.3. vector modfication
1410
1411(vset 'v_vect 'x_index 'g_val)
1412(vseti-byte 'V_vect 'x_bindex 'x_val)
1413(vseti-word 'V_vect 'x_windex 'x_val)
1414(vseti-long 'V_vect 'x_lindex 'x_val)
1415
1416 RETURNS: the datum.
1417
1418 SIDE EFFECT: The indexed element of the vector is set
1419 to the value. As noted above, for vseti-
1420 word and vseti-byte, the index is con-
1421 strued as the number of the data element
1422 within the vector. It is not a byte
1423 address. Also, for those two functions,
1424 the low order byte or word of x_val is
1425 what is stored.
1426
1427(vsetprop 'Vv_vect 'g_value)
1428
1429 RETURNS: g_value. This should be either a symbol or a
1430 disembodied property list whose _\bc_\ba_\br is a sym-
1431 bol identifying the type of the vector.
1432
1433 SIDE EFFECT: the property list of Vv_vect is set to
1434 g_value.
1435
1436(vputprop 'Vv_vect 'g_value 'g_ind)
1437
1438 RETURNS: g_value.
1439
1440 SIDE EFFECT: If the vector property of Vv_vect is a
1441 disembodied property list, then vputprop
1442 adds the value g_value under the indicator
1443 g_ind. Otherwise, the old vector property
1444 is made the first element of the list.
1445
1446
1447
1448
1449\e9
1450
1451\e9 Printed: January 31, 1984
1452
1453
1454
1455
1456
1457
1458
1459Data Structure Access 2-23
1460
1461
1462 2.5. Arrays
1463
1464 See Chapter 9 for a complete description of
1465 arrays. Some of these functions are part of a Maclisp
1466 array compatibility package representing only one sim-
1467 ple way of using the array structure of FRANZ LISP.
1468
1469
1470
1471 2.5.1. array creation
1472
1473(marray 'g_data 's_access 'g_aux 'x_length 'x_delta)
1474
1475 RETURNS: an array type with the fields set up from the
1476 above arguments in the obvious way (see
1477 1.2.10).
1478
1479(*array 's_name 's_type 'x_dim1 ... 'x_dim_\bn)
1480(array s_name s_type x_dim1 ... x_dim_\bn)
1481
1482 WHERE: s_type may be one of t, nil, fixnum, flonum,
1483 fixnum-block and flonum-block.
1484
1485 RETURNS: an array of type s_type with n dimensions of
1486 extents given by the x_dim_\bi.
1487
1488 SIDE EFFECT: If s_name is non nil, the function defini-
1489 tion of s_name is set to the array struc-
1490 ture returned.
1491
1492 NOTE: These functions create a Maclisp compatible
1493 array. In FRANZ LISP arrays of type t, nil, fix-
1494 num and flonum are equivalent and the elements of
1495 these arrays can be any type of lisp object.
1496 Fixnum-block and flonum-block arrays are res-
1497 tricted to fixnums and flonums respectively and
1498 are used mainly to communicate with foreign func-
1499 tions (see 8.5).
1500
1501 NOTE: *_\ba_\br_\br_\ba_\by evaluates its arguments, _\ba_\br_\br_\ba_\by does not.
1502
1503
1504
1505 2.5.2. array predicate
1506
1507
1508
1509
1510
1511
1512
1513
1514\e9
1515
1516\e9 Printed: January 31, 1984
1517
1518
1519
1520
1521
1522
1523
1524Data Structure Access 2-24
1525
1526
1527(arrayp 'g_arg)
1528
1529 RETURNS: t iff g_arg is of type array.
1530
1531
1532
1533 2.5.3. array accessors
1534
1535
1536(getaccess 'a_array)
1537(getaux 'a_array)
1538(getdelta 'a_array)
1539(getdata 'a_array)
1540(getlength 'a_array)
1541
1542 RETURNS: the field of the array object a_array given by
1543 the function name.
1544
1545(arrayref 'a_name 'x_ind)
1546
1547 RETURNS: the x_ind_\bt_\bh element of the array object
1548 a_name. x_ind of zero accesses the first ele-
1549 ment.
1550
1551 NOTE: _\ba_\br_\br_\ba_\by_\br_\be_\bf uses the data, length and delta fields
1552 of a_name to determine which object to return.
1553
1554(arraycall s_type 'as_array 'x_ind1 ... )
1555
1556 RETURNS: the element selected by the indices from the
1557 array a_array of type s_type.
1558
1559 NOTE: If as_array is a symbol then the function binding
1560 of this symbol should contain an array object.
1561 s_type is ignored by _\ba_\br_\br_\ba_\by_\bc_\ba_\bl_\bl but is included
1562 for compatibility with Maclisp.
1563
1564(arraydims 's_name)
1565
1566 RETURNS: a list of the type and bounds of the array
1567 s_name.
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579\e9
1580
1581\e9 Printed: January 31, 1984
1582
1583
1584
1585
1586
1587
1588
1589Data Structure Access 2-25
1590
1591
1592(listarray 'sa_array ['x_elements])
1593
1594 RETURNS: a list of all of the elements in array
1595 sa_array. If x_elements is given, then only
1596 the first x_elements are returned.
1597
1598
1599
1600 ____________________________________________________
1601
1602 ; We will create a 3 by 4 array of general lisp objects
1603 -> (_\ba_\br_\br_\ba_\by _\be_\br_\bn_\bi_\be _\bt _\b3 _\b4)
1604 array[12]
1605
1606 ; the array header is stored in the function definition slot of the
1607 ; symbol ernie
1608 -> (_\ba_\br_\br_\ba_\by_\bp (_\bg_\be_\bt_\bd '_\be_\br_\bn_\bi_\be))
1609 t
1610 -> (_\ba_\br_\br_\ba_\by_\bd_\bi_\bm_\bs (_\bg_\be_\bt_\bd '_\be_\br_\bn_\bi_\be))
1611 (t 3 4)
1612
1613 ; store in ernie[2][2] the list (test list)
1614 -> (_\bs_\bt_\bo_\br_\be (_\be_\br_\bn_\bi_\be _\b2 _\b2) '(_\bt_\be_\bs_\bt _\bl_\bi_\bs_\bt))
1615 (test list)
1616
1617 ; check to see if it is there
1618 -> (_\be_\br_\bn_\bi_\be _\b2 _\b2)
1619 (test list)
1620
1621 ; now use the low level function _\ba_\br_\br_\ba_\by_\br_\be_\bf to find the same element
1622 ; arrays are 0 based and row-major (the last subscript varies the fastest)
1623 ; thus element [2][2] is the 10th element , (starting at 0).
1624 -> (_\ba_\br_\br_\ba_\by_\br_\be_\bf (_\bg_\be_\bt_\bd '_\be_\br_\bn_\bi_\be) _\b1_\b0)
1625 (ptr to)(test list) ; the result is a value cell (thus the (ptr to))
1626 ____________________________________________________
1627
1628
1629
1630
1631
1632
1633 2.5.4. array manipulation
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644\e9
1645
1646\e9 Printed: January 31, 1984
1647
1648
1649
1650
1651
1652
1653
1654Data Structure Access 2-26
1655
1656
1657(putaccess 'a_array 'su_func)
1658(putaux 'a_array 'g_aux)
1659(putdata 'a_array 'g_arg)
1660(putdelta 'a_array 'x_delta)
1661(putlength 'a_array 'x_length)
1662
1663 RETURNS: the second argument to the function.
1664
1665 SIDE EFFECT: The field of the array object given by the
1666 function name is replaced by the second
1667 argument to the function.
1668
1669(store 'l_arexp 'g_val)
1670
1671 WHERE: l_arexp is an expression which references an
1672 array element.
1673
1674 RETURNS: g_val
1675
1676 SIDE EFFECT: the array location which contains the ele-
1677 ment which l_arexp references is changed
1678 to contain g_val.
1679
1680(fillarray 's_array 'l_itms)
1681
1682 RETURNS: s_array
1683
1684 SIDE EFFECT: the array s_array is filled with elements
1685 from l_itms. If there are not enough ele-
1686 ments in l_itms to fill the entire array,
1687 then the last element of l_itms is used to
1688 fill the remaining parts of the array.
1689
1690
1691
1692 2.6. Hunks
1693
1694 Hunks are vector-like objects whose size can
1695 range from 1 to 128 elements. Internally, hunks are
1696 allocated in sizes which are powers of 2. In order to
1697 create hunks of a given size, a hunk with at least
1698 that many elements is allocated and a distinguished
1699 symbol EMPTY is placed in those elements not
1700 requested. Most hunk functions respect those dis-
1701 tinguished symbols, but there are two (*_\bm_\ba_\bk_\bh_\bu_\bn_\bk and
1702 *_\br_\bp_\bl_\ba_\bc_\bx) which will overwrite the distinguished sym-
1703 bol.
1704
1705
1706
1707
1708
1709\e9
1710
1711\e9 Printed: January 31, 1984
1712
1713
1714
1715
1716
1717
1718
1719Data Structure Access 2-27
1720
1721
1722 2.6.1. hunk creation
1723
1724(hunk 'g_val1 ['g_val2 ... 'g_val_\bn])
1725
1726 RETURNS: a hunk of length n whose elements are initial-
1727 ized to the g_val_\bi.
1728
1729 NOTE: the maximum size of a hunk is 128.
1730
1731 EXAMPLE: (_\bh_\bu_\bn_\bk _\b4 '_\bs_\bh_\ba_\br_\bp '_\bk_\be_\by_\bs) = {4 sharp keys}
1732
1733(makhunk 'xl_arg)
1734
1735 RETURNS: a hunk of length xl_arg initialized to all
1736 nils if xl_arg is a fixnum. If xl_arg is a
1737 list, then we return a hunk of size
1738 (_\bl_\be_\bn_\bg_\bt_\bh '_\bx_\bl__\ba_\br_\bg) initialized to the elements
1739 in xl_arg.
1740
1741 NOTE: (_\bm_\ba_\bk_\bh_\bu_\bn_\bk '(_\ba _\bb _\bc)) is equivalent to
1742 (_\bh_\bu_\bn_\bk '_\ba '_\bb '_\bc).
1743
1744 EXAMPLE: (_\bm_\ba_\bk_\bh_\bu_\bn_\bk _\b4) = {_\bn_\bi_\bl _\bn_\bi_\bl _\bn_\bi_\bl _\bn_\bi_\bl}
1745
1746(*makhunk 'x_arg)
1747
1748 RETURNS: a hunk of size 2[x_arg] initialized to EMPTY.
1749
1750 NOTE: This is only to be used by such functions as _\bh_\bu_\bn_\bk
1751 and _\bm_\ba_\bk_\bh_\bu_\bn_\bk which create and initialize hunks for
1752 users.
1753
1754
1755
1756 2.6.2. hunk accessor
1757
1758(cxr 'x_ind 'h_hunk)
1759
1760 RETURNS: element x_ind (starting at 0) of hunk h_hunk.
1761
1762(hunk-to-list 'h_hunk)
1763
1764 RETURNS: a list consisting of the elements of h_hunk.
1765
1766
1767
1768 2.6.3. hunk manipulators
1769
1770
1771
1772
1773
1774\e9
1775
1776\e9 Printed: January 31, 1984
1777
1778
1779
1780
1781
1782
1783
1784Data Structure Access 2-28
1785
1786
1787(rplacx 'x_ind 'h_hunk 'g_val)
1788(*rplacx 'x_ind 'h_hunk 'g_val)
1789
1790 RETURNS: h_hunk
1791
1792 SIDE EFFECT: Element x_ind (starting at 0) of h_hunk is
1793 set to g_val.
1794
1795 NOTE: _\br_\bp_\bl_\ba_\bc_\bx will not modify one of the distinguished
1796 (EMPTY) elements whereas *_\br_\bp_\bl_\ba_\bc_\bx will.
1797
1798(hunksize 'h_arg)
1799
1800 RETURNS: the size of the hunk h_arg.
1801
1802 EXAMPLE: (_\bh_\bu_\bn_\bk_\bs_\bi_\bz_\be (_\bh_\bu_\bn_\bk _\b1 _\b2 _\b3)) = 3
1803
1804
1805
1806 2.7. Bcds
1807
1808 A bcd object contains a pointer to compiled code
1809 and to the type of function object the compiled code
1810 represents.
1811
1812(getdisc 'y_bcd)
1813(getentry 'y_bcd)
1814
1815 RETURNS: the field of the bcd object given by the func-
1816 tion name.
1817
1818(putdisc 'y_func 's_discipline)
1819
1820 RETURNS: s_discipline
1821
1822 SIDE EFFECT: Sets the discipline field of y_func to
1823 s_discipline.
1824
1825
1826
1827 2.8. Structures
1828
1829 There are three common structures constructed out
1830 of list cells: the assoc list, the property list and
1831 the tconc list. The functions below manipulate these
1832 structures.
1833
1834
1835
1836 2.8.1. assoc list
1837
1838 An `assoc list' (or alist) is a common lisp
1839 data structure. It has the form
1840
1841
1842 Printed: January 31, 1984
1843
1844
1845
1846
1847
1848
1849
1850Data Structure Access 2-29
1851
1852
1853 ((key1 . value1) (key2 . value2) (key3 . value3) ... (keyn . valuen))
1854
1855(assoc 'g_arg1 'l_arg2)
1856(assq 'g_arg1 'l_arg2)
1857
1858 RETURNS: the first top level element of l_arg2 whose
1859 _\bc_\ba_\br is _\be_\bq_\bu_\ba_\bl (with _\ba_\bs_\bs_\bo_\bc) or _\be_\bq (with _\ba_\bs_\bs_\bq) to
1860 g_arg1.
1861
1862 NOTE: Usually l_arg2 has an _\ba-_\bl_\bi_\bs_\bt structure and g_arg1
1863 acts as key.
1864
1865(sassoc 'g_arg1 'l_arg2 'sl_func)
1866
1867 RETURNS: the result of
1868 (_\bc_\bo_\bn_\bd ((_\ba_\bs_\bs_\bo_\bc '_\bg__\ba_\br_\bg '_\bl__\ba_\br_\bg_\b2) (_\ba_\bp_\bp_\bl_\by '_\bs_\bl__\bf_\bu_\bn_\bc _\bn_\bi_\bl)))
1869
1870 NOTE: sassoc is written as a macro.
1871
1872(sassq 'g_arg1 'l_arg2 'sl_func)
1873
1874 RETURNS: the result of
1875 (_\bc_\bo_\bn_\bd ((_\ba_\bs_\bs_\bq '_\bg__\ba_\br_\bg '_\bl__\ba_\br_\bg_\b2) (_\ba_\bp_\bp_\bl_\by '_\bs_\bl__\bf_\bu_\bn_\bc _\bn_\bi_\bl)))
1876
1877 NOTE: sassq is written as a macro.
1878
1879
1880
1881 ____________________________________________________
1882
1883 ; _\ba_\bs_\bs_\bo_\bc or _\ba_\bs_\bs_\bq is given a key and an assoc list and returns
1884 ; the key and value item if it exists, they differ only in how they test
1885 ; for equality of the keys.
1886
1887 -> (_\bs_\be_\bt_\bq _\ba_\bl_\bi_\bs_\bt '((_\ba_\bl_\bp_\bh_\ba . _\ba) ( (_\bc_\bo_\bm_\bp_\bl_\be_\bx _\bk_\be_\by) . _\bb) (_\bj_\bu_\bn_\bk . _\bx)))
1888 ((alpha . a) ((complex key) . b) (junk . x))
1889
1890 ; we should use _\ba_\bs_\bs_\bq when the key is an atom
1891 -> (_\ba_\bs_\bs_\bq '_\ba_\bl_\bp_\bh_\ba _\ba_\bl_\bi_\bs_\bt)
1892 (alpha . a)
1893
1894 ; but it may not work when the key is a list
1895 -> (_\ba_\bs_\bs_\bq '(_\bc_\bo_\bm_\bp_\bl_\be_\bx _\bk_\be_\by) _\ba_\bl_\bi_\bs_\bt)
1896 nil
1897
1898 ; however _\ba_\bs_\bs_\bo_\bc will always work
1899 -> (_\ba_\bs_\bs_\bo_\bc '(_\bc_\bo_\bm_\bp_\bl_\be_\bx _\bk_\be_\by) _\ba_\bl_\bi_\bs_\bt)
1900 ((complex key) . b)
1901 ____________________________________________________
1902
1903
1904
1905\e9
1906
1907\e9 Printed: January 31, 1984
1908
1909
1910
1911
1912
1913
1914
1915Data Structure Access 2-30
1916
1917
1918(sublis 'l_alst 'l_exp)
1919
1920 WHERE: l_alst is an _\ba-_\bl_\bi_\bs_\bt.
1921
1922 RETURNS: the list l_exp with every occurrence of key_\bi
1923 replaced by val_\bi.
1924
1925 NOTE: new list structure is returned to prevent modifi-
1926 cation of l_exp. When a substitution is made, a
1927 copy of the value to substitute in is not made.
1928
1929
1930
1931 2.8.2. property list
1932
1933 A property list consists of an alternating
1934 sequence of keys and values. Normally a property
1935 list is stored on a symbol. A list is a 'disembo-
1936 died' property list if it contains an odd number of
1937 elements, the first of which is ignored.
1938
1939(plist 's_name)
1940
1941 RETURNS: the property list of s_name.
1942
1943(setplist 's_atm 'l_plist)
1944
1945 RETURNS: l_plist.
1946
1947 SIDE EFFECT: the property list of s_atm is set to
1948 l_plist.
1949
1950
1951(get 'ls_name 'g_ind)
1952
1953 RETURNS: the value under indicator g_ind in ls_name's
1954 property list if ls_name is a symbol.
1955
1956 NOTE: If there is no indicator g_ind in ls_name's pro-
1957 perty list nil is returned. If ls_name is a list
1958 of an odd number of elements then it is a disem-
1959 bodied property list. _\bg_\be_\bt searches a disembodied
1960 property list by starting at its _\bc_\bd_\br, and compar-
1961 ing every other element with g_ind, using _\be_\bq.
1962
1963
1964
1965
1966
1967
1968
1969
1970\e9
1971
1972\e9 Printed: January 31, 1984
1973
1974
1975
1976
1977
1978
1979
1980Data Structure Access 2-31
1981
1982
1983(getl 'ls_name 'l_indicators)
1984
1985 RETURNS: the property list ls_name beginning at the
1986 first indicator which is a member of the list
1987 l_indicators, or nil if none of the indicators
1988 in l_indicators are on ls_name's property
1989 list.
1990
1991 NOTE: If ls_name is a list, then it is assumed to be a
1992 disembodied property list.
1993
1994
1995(putprop 'ls_name 'g_val 'g_ind)
1996(defprop ls_name g_val g_ind)
1997
1998 RETURNS: g_val.
1999
2000 SIDE EFFECT: Adds to the property list of ls_name the
2001 value g_val under the indicator g_ind.
2002
2003 NOTE: _\bp_\bu_\bt_\bp_\br_\bo_\bp evaluates it arguments, _\bd_\be_\bf_\bp_\br_\bo_\bp does not.
2004 ls_name may be a disembodied property list, see
2005 _\bg_\be_\bt.
2006
2007(remprop 'ls_name 'g_ind)
2008
2009 RETURNS: the portion of ls_name's property list begin-
2010 ning with the property under the indicator
2011 g_ind. If there is no g_ind indicator in
2012 ls_name's plist, nil is returned.
2013
2014 SIDE EFFECT: the value under indicator g_ind and g_ind
2015 itself is removed from the property list
2016 of ls_name.
2017
2018 NOTE: ls_name may be a disembodied property list, see
2019 _\bg_\be_\bt.
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035\e9
2036
2037\e9 Printed: January 31, 1984
2038
2039
2040
2041
2042
2043
2044
2045Data Structure Access 2-32
2046
2047
2048
2049 ____________________________________________________
2050
2051 -> (_\bp_\bu_\bt_\bp_\br_\bo_\bp '_\bx_\bl_\ba_\bt_\be '_\ba '_\ba_\bl_\bp_\bh_\ba)
2052 a
2053 -> (_\bp_\bu_\bt_\bp_\br_\bo_\bp '_\bx_\bl_\ba_\bt_\be '_\bb '_\bb_\be_\bt_\ba)
2054 b
2055 -> (_\bp_\bl_\bi_\bs_\bt '_\bx_\bl_\ba_\bt_\be)
2056 (alpha a beta b)
2057 -> (_\bg_\be_\bt '_\bx_\bl_\ba_\bt_\be '_\ba_\bl_\bp_\bh_\ba)
2058 a
2059 ; use of a disembodied property list:
2060 -> (_\bg_\be_\bt '(_\bn_\bi_\bl _\bf_\ba_\bt_\be_\bm_\ba_\bn _\br_\bj_\bf _\bs_\bk_\bl_\bo_\bw_\be_\br _\bk_\bl_\bs _\bf_\bo_\bd_\be_\br_\ba_\br_\bo _\bj_\bk_\bf) '_\bs_\bk_\bl_\bo_\bw_\be_\br)
2061 kls
2062 ____________________________________________________
2063
2064
2065
2066
2067
2068
2069 2.8.3. tconc structure
2070
2071 A tconc structure is a special type of list
2072 designed to make it easy to add objects to the end.
2073 It consists of a list cell whose _\bc_\ba_\br points to a
2074 list of the elements added with _\bt_\bc_\bo_\bn_\bc or _\bl_\bc_\bo_\bn_\bc and
2075 whose _\bc_\bd_\br points to the last list cell of the list
2076 pointed to by the _\bc_\ba_\br.
2077
2078(tconc 'l_ptr 'g_x)
2079
2080 WHERE: l_ptr is a tconc structure.
2081
2082 RETURNS: l_ptr with g_x added to the end.
2083
2084(lconc 'l_ptr 'l_x)
2085
2086 WHERE: l_ptr is a tconc structure.
2087
2088 RETURNS: l_ptr with the list l_x spliced in at the end.
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100\e9
2101
2102\e9 Printed: January 31, 1984
2103
2104
2105
2106
2107
2108
2109
2110Data Structure Access 2-33
2111
2112
2113
2114 ____________________________________________________
2115
2116 ; A _\bt_\bc_\bo_\bn_\bc structure can be initialized in two ways.
2117 ; nil can be given to _\bt_\bc_\bo_\bn_\bc in which case _\bt_\bc_\bo_\bn_\bc will generate
2118 ; a _\bt_\bc_\bo_\bn_\bc structure.
2119
2120 ->(_\bs_\be_\bt_\bq _\bf_\bo_\bo (_\bt_\bc_\bo_\bn_\bc _\bn_\bi_\bl _\b1))
2121 ((1) 1)
2122
2123 ; Since _\bt_\bc_\bo_\bn_\bc destructively adds to
2124 ; the list, you can now add to foo without using _\bs_\be_\bt_\bq again.
2125
2126 ->(_\bt_\bc_\bo_\bn_\bc _\bf_\bo_\bo _\b2)
2127 ((1 2) 2)
2128 ->_\bf_\bo_\bo
2129 ((1 2) 2)
2130
2131 ; Another way to create a null _\bt_\bc_\bo_\bn_\bc structure
2132 ; is to use (_\bn_\bc_\bo_\bn_\bs _\bn_\bi_\bl).
2133
2134 ->(_\bs_\be_\bt_\bq _\bf_\bo_\bo (_\bn_\bc_\bo_\bn_\bs _\bn_\bi_\bl))
2135 (nil)
2136 ->(_\bt_\bc_\bo_\bn_\bc _\bf_\bo_\bo _\b1)
2137 ((1) 1)
2138
2139 ; now see what _\bl_\bc_\bo_\bn_\bc can do
2140 -> (_\bl_\bc_\bo_\bn_\bc _\bf_\bo_\bo _\bn_\bi_\bl)
2141 ((1) 1) ; no change
2142 -> (_\bl_\bc_\bo_\bn_\bc _\bf_\bo_\bo '(_\b2 _\b3 _\b4))
2143 ((1 2 3 4) 4)
2144 ____________________________________________________
2145
2146
2147
2148
2149
2150
2151 2.8.4. fclosures
2152
2153 An fclosure is a functional object which
2154 admits some data manipulations. They are discussed
2155 in 8.4. Internally, they are constructed from vec-
2156 tors.
2157
2158
2159
2160
2161
2162
2163
2164
2165\e9
2166
2167\e9 Printed: January 31, 1984
2168
2169
2170
2171
2172
2173
2174
2175Data Structure Access 2-34
2176
2177
2178(fclosure 'l_vars 'g_funobj)
2179
2180 WHERE: l_vars is a list of variables, g_funobj is any
2181 object that can be funcalled (including, fclo-
2182 sures).
2183
2184 RETURNS: A vector which is the fclosure.
2185
2186(fclosure-alist 'v_fclosure)
2187
2188 RETURNS: An association list representing the variables
2189 in the fclosure. This is a snapshot of the
2190 current state of the fclosure. If the bind-
2191 ings in the fclosure are changed, any previ-
2192 ously calculated results of _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be-_\ba_\bl_\bi_\bs_\bt
2193 will not change.
2194
2195(fclosure-function 'v_fclosure)
2196
2197 RETURNS: the functional object part of the fclosure.
2198
2199(fclosurep 'v_fclosure)
2200
2201 RETURNS: t iff the argument is an fclosure.
2202
2203(symeval-in-fclosure 'v_fclosure 's_symbol)
2204
2205 RETURNS: the current binding of a particular symbol in
2206 an fclosure.
2207
2208(set-in-fclosure 'v_fclosure 's_symbol 'g_newvalue)
2209
2210 RETURNS: g_newvalue.
2211
2212 SIDE EFFECT: The variable s_symbol is bound in the
2213 fclosure to g_newvalue.
2214
2215
2216
2217 2.9. Random functions
2218
2219 The following functions don't fall into any of
2220 the classifications above.
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230\e9
2231
2232\e9 Printed: January 31, 1984
2233
2234
2235
2236
2237
2238
2239
2240Data Structure Access 2-35
2241
2242
2243(bcdad 's_funcname)
2244
2245 RETURNS: a fixnum which is the address in memory where
2246 the function s_funcname begins. If s_funcname
2247 is not a machine coded function (binary) then
2248 _\bb_\bc_\bd_\ba_\bd returns nil.
2249
2250(copy 'g_arg)
2251
2252 RETURNS: A structure _\be_\bq_\bu_\ba_\bl to g_arg but with new list
2253 cells.
2254
2255(copyint* 'x_arg)
2256
2257 RETURNS: a fixnum with the same value as x_arg but in a
2258 freshly allocated cell.
2259
2260(cpy1 'xvt_arg)
2261
2262 RETURNS: a new cell of the same type as xvt_arg with
2263 the same value as xvt_arg.
2264
2265(getaddress 's_entry1 's_binder1 'st_discipline1 [... ...
2266...])
2267
2268 RETURNS: the binary object which s_binder1's function
2269 field is set to.
2270
2271 NOTE: This looks in the running lisp's symbol table for
2272 a symbol with the same name as s_entry_\bi. It then
2273 creates a binary object whose entry field points
2274 to s_entry_\bi and whose discipline is
2275 st_discipline_\bi. This binary object is stored in
2276 the function field of s_binder_\bi. If
2277 st_discipline_\bi is nil, then "subroutine" is used
2278 by default. This is especially useful for _\bc_\bf_\ba_\bs_\bl
2279 users.
2280
2281(macroexpand 'g_form)
2282
2283 RETURNS: g_form after all macros in it are expanded.
2284
2285 NOTE: This function will only macroexpand expressions
2286 which could be evaluated and it does not know
2287 about the special nlambdas such as _\bc_\bo_\bn_\bd and _\bd_\bo,
2288 thus it misses many macro expansions.
2289
2290
2291
2292
2293
2294
2295\e9
2296
2297\e9 Printed: January 31, 1984
2298
2299
2300
2301
2302
2303
2304
2305Data Structure Access 2-36
2306
2307
2308(ptr 'g_arg)
2309
2310 RETURNS: a value cell initialized to point to g_arg.
2311
2312(quote g_arg)
2313
2314 RETURNS: g_arg.
2315
2316 NOTE: the reader allows you to abbreviate (quote foo)
2317 as 'foo.
2318
2319(kwote 'g_arg)
2320
2321 RETURNS: (_\bl_\bi_\bs_\bt (_\bq_\bu_\bo_\bt_\be _\bq_\bu_\bo_\bt_\be) _\bg__\ba_\br_\bg).
2322
2323(replace 'g_arg1 'g_arg2)
2324
2325 WHERE: g_arg1 and g_arg2 must be the same type of
2326 lispval and not symbols or hunks.
2327
2328 RETURNS: g_arg2.
2329
2330 SIDE EFFECT: The effect of _\br_\be_\bp_\bl_\ba_\bc_\be is dependent on the
2331 type of the g_arg_\bi although one will
2332 notice a similarity in the effects. To
2333 understand what _\br_\be_\bp_\bl_\ba_\bc_\be does to fixnum and
2334 flonum arguments, you must first under-
2335 stand that such numbers are `boxed' in
2336 FRANZ LISP. What this means is that if
2337 the symbol x has a value 32412, then in
2338 memory the value element of x's symbol
2339 structure contains the address of another
2340 word of memory (called a box) with 32412
2341 in it.
2342
2343 Thus, there are two ways of changing the
2344 value of x: the first is to change the
2345 value element of x's symbol structure to
2346 point to a word of memory with a different
2347 value. The second way is to change the
2348 value in the box which x points to. The
2349 former method is used almost all of the
2350 time, the latter is used very rarely and
2351 has the potential to cause great confu-
2352 sion. The function _\br_\be_\bp_\bl_\ba_\bc_\be allows you to
2353 do the latter, i.e., to actually change
2354 the value in the box.
2355
2356 You should watch out for these situations.
2357 If you do (_\bs_\be_\bt_\bq _\by _\bx), then both x and y
2358 will point to the same box. If you now
2359 (_\br_\be_\bp_\bl_\ba_\bc_\be _\bx _\b1_\b2_\b3_\b4_\b5), then y will also have
2360 the value 12345. And, in fact, there may
2361
2362
2363 Printed: January 31, 1984
2364
2365
2366
2367
2368
2369
2370
2371Data Structure Access 2-37
2372
2373
2374 be many other pointers to that box.
2375
2376 Another problem with replacing fixnums is
2377 that some boxes are read-only. The fix-
2378 nums between -1024 and 1023 are stored in
2379 a read-only area and attempts to replace
2380 them will result in an "Illegal memory
2381 reference" error (see the description of
2382 _\bc_\bo_\bp_\by_\bi_\bn_\bt* for a way around this problem).
2383
2384 For the other valid types, the effect of
2385 _\br_\be_\bp_\bl_\ba_\bc_\be is easy to understand. The fields
2386 of g_val1's structure are made eq to the
2387 corresponding fields of g_val2's struc-
2388 ture. For example, if x and y have
2389 lists as values then the effect of
2390 (_\br_\be_\bp_\bl_\ba_\bc_\be _\bx _\by) is the same as
2391 (_\br_\bp_\bl_\ba_\bc_\ba _\bx (_\bc_\ba_\br _\by)) and (_\br_\bp_\bl_\ba_\bc_\bd _\bx (_\bc_\bd_\br _\by)).
2392
2393(scons 'x_arg 'bs_rest)
2394
2395 WHERE: bs_rest is a bignum or nil.
2396
2397 RETURNS: a bignum whose first bigit is x_arg and whose
2398 higher order bigits are bs_rest.
2399
2400(setf g_refexpr 'g_value)
2401
2402 NOTE: _\bs_\be_\bt_\bf is a generalization of setq. Information
2403 may be stored by binding variables, replacing
2404 entries of arrays, and vectors, or being put on
2405 property lists, among others. Setf will allow
2406 the user to store data into some location, by
2407 mentioning the operation used to refer to the
2408 location. Thus, the first argument may be par-
2409 tially evaluated, but only to the extent needed
2410 to calculate a reference. _\bs_\be_\bt_\bf returns g_value.
2411 (Compare to _\bd_\be_\bs_\be_\bt_\bq )
2412
2413
2414 ____________________________________________________
2415
2416 (setf x 3) = (setq x 3)
2417 (setf (car x) 3) = (rplaca x 3)
2418 (setf (get foo 'bar) 3) = (putprop foo 3 'bar)
2419 (setf (vref vector index) value) = (vset vector index value)
2420 ____________________________________________________
2421
2422
2423
2424
2425
2426\e9
2427
2428\e9 Printed: January 31, 1984
2429
2430
2431
2432
2433
2434
2435
2436Data Structure Access 2-38
2437
2438
2439(sort 'l_data 'u_comparefn)
2440
2441 RETURNS: a list of the elements of l_data ordered by
2442 the comparison function u_comparefn.
2443
2444 SIDE EFFECT: the list l_data is modified rather than
2445 allocated in new storage.
2446
2447 NOTE: (_\bc_\bo_\bm_\bp_\ba_\br_\be_\bf_\bn '_\bg__\bx '_\bg__\by) should return something
2448 non-nil if g_x can precede g_y in sorted order;
2449 nil if g_y must precede g_x. If u_comparefn is
2450 nil, alphabetical order will be used.
2451
2452(sortcar 'l_list 'u_comparefn)
2453
2454 RETURNS: a list of the elements of l_list with the
2455 _\bc_\ba_\br's ordered by the sort function
2456 u_comparefn.
2457
2458 SIDE EFFECT: the list l_list is modified rather than
2459 copied.
2460
2461 NOTE: Like _\bs_\bo_\br_\bt, if u_comparefn is nil, alphabetical
2462 order will be used.
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491\e9
2492
2493\e9 Printed: January 31, 1984
2494
2495
2496
Continuous source code history from original PDP-7 UNIX to FreeBSD 2, the first fully unencumbered FreeBSD release.