![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch2.r CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / ucb / lisp / lisplib / manual|
Return to ch2.r CVS log | Up to [CSRG BSD Unix] / 43BSD / ucb / lisp / lisplib / manual |
1.1 root 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-
17: late the various types of lisp data structures. Refer to
18: 1.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: (_c_o_n_s '_g__a_r_g_2 '_g__a_r_g_1)
43:
44: (ncons 'g_arg)
45:
46: EQUIVALENT TO: (_c_o_n_s '_g__a_r_g _n_i_l)
47:
48: (list ['g_arg1 ... ])
49:
50: RETURNS: a list whose elements are the g_arg_i.
51:
52:
53:
54:
55:
56:
57:
58:
59:
60: 9
61:
62: 9Data Structure Access 2-1
63:
64:
65:
66:
67:
68:
69:
70: Data 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 _n_c_o_n_c and _t_c_o_n_c for
83: cheaper ways of doing the _a_p_p_e_n_d 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: -> (_a_p_p_e_n_d '(_a _b _c _d) '_e)
99: (a b c d . e)
100: ; The user intended to say:
101: -> (_a_p_p_e_n_d '(_a _b _c _d) '(_e))
102: (_a _b _c _d _e)
103: ; _b_e_t_t_e_r _i_s _a_p_p_e_n_d_1
104: -> (_a_p_p_e_n_d_1 '(_a _b _c _d) '_e)
105: (_a _b _c _d _e)
106: ____________________________________________________
107:
108:
109:
110:
111: (quote! [g_qform_i] ...[! 'g_eform_i] ... [!! 'l_form_i] ...)
112:
113: RETURNS: The list resulting from the splicing and
114: insertion process described below.
115:
116: NOTE: _q_u_o_t_e! is the complement of the _l_i_s_t function.
117: _l_i_s_t forms a list by evaluating each for in the
118: argument list; evaluation is suppressed if the
119: form is _q_u_o_t_eed. In _q_u_o_t_e!, each form is impli-
120: citly _q_u_o_t_eed. 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:
136: Data 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 _q_u_o_t_e! func-
145: tion is to use the backquote character macro (see
146: 8.3.3).
147:
148:
149: ____________________________________________________
150:
151: (_q_u_o_t_e! _c_o_n_s ! (_c_o_n_s _1 _2) _3) = (_c_o_n_s (_1 . _2) _3)
152: (_q_u_o_t_e! _1 !! (_l_i_s_t _2 _3 _4) _5) = (_1 _2 _3 _4 _5)
153: (_s_e_t_q _q_u_o_t_e_d '_e_v_a_l_e_d)(_q_u_o_t_e! ! ((_I _a_m ! _q_u_o_t_e_d))) = ((_I _a_m _e_v_a_l_e_d))
154: (_q_u_o_t_e! _t_r_y ! '(_t_h_i_s ! _o_n_e)) = (_t_r_y (_t_h_i_s ! _o_n_e))
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 _l_i_s_t-_t_o-_b_i_g_n_u_m.
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 _b_i_g_n_u_m-_t_o-_l_i_s_t.
175:
176:
177:
178:
179: 2.1.2. list predicates
180:
181:
182:
183:
184:
185:
186:
187:
188:
189:
190:
191: 9
192:
193: 9 Printed: January 31, 1984
194:
195:
196:
197:
198:
199:
200:
201: Data 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 _e_q to l_x is found by
218: _c_d_ring down l_y zero or more times, nil other-
219: wise.
220:
221:
222: ____________________________________________________
223:
224: -> (_s_e_t_q _x '(_a _b _c _d) _y (_c_d_d_r _x))
225: (c d)
226: -> (_a_n_d (_d_t_p_r _x) (_l_i_s_t_p _x)) ; x and y are dtprs and lists
227: t
228: -> (_d_t_p_r '()) ; () is the same as nil and is not a dtpr
229: nil
230: -> (_l_i_s_t_p '()) ; however it is a list
231: t
232: -> (_t_a_i_l_p _y _x)
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: 9
257:
258: 9 Printed: January 31, 1984
259:
260:
261:
262:
263:
264:
265:
266: Data Structure Access 2-5
267:
268:
269: (car 'l_arg)
270: (cdr 'l_arg)
271:
272: RETURNS: _c_o_n_s cell. (_c_a_r (_c_o_n_s x y)) is always x, (_c_d_r
273: (_c_o_n_s 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 (_c_a_r '_l_h__a_r_g) is the same as
292: (_c_x_r _1 '_l_h__a_r_g) and (_c_d_r '_l_h__a_r_g) is the same as
293: (_c_x_r _0 '_l_h__a_r_g).
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). _n_t_h is both a function, and a
305: compiler macro, so that more efficient code
306: might be generated than for _n_t_h_e_l_e_m (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: 9
322:
323: 9 Printed: January 31, 1984
324:
325:
326:
327:
328:
329:
330:
331: Data Structure Access 2-6
332:
333:
334: (nthcdr 'x_index 'l_list)
335:
336: RETURNS: the result of _c_d_ring down the list l_list
337: x_index times.
338:
339: NOTE: If x_index is less than 0, then
340: (_c_o_n_s _n_i_l '_l__l_i_s_t) is returned.
341:
342: (nthelem 'x_arg1 'l_arg2)
343:
344: RETURNS: The x_arg1'_s_t 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: _l_a_s_t does NOT return the last element of a
353: list!
354: (_l_a_s_t '(_a _b)) = (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., _e_q to the result
362: of applying some number of _c_d_r's to l_x. Note
363: that the value of _l_d_i_f_f is always new
364: list structure unless l_y is nil, in which case
365: (_l_d_i_f_f _l__x _n_i_l) is l_x itself. If l_y is not
366: a tail of l_x, _l_d_i_f_f generates an error.
367:
368: EXAMPLE: (_l_d_i_f_f '_l__x (_m_e_m_b_e_r '_g__f_o_o '_l__x)) 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: 9
387:
388: 9 Printed: January 31, 1984
389:
390:
391:
392:
393:
394:
395:
396: Data 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 _c_a_r is now g_x, whose _c_a_d_r is the
411: original (_c_a_r _l__l), and whose _c_d_d_r is the ori-
412: ginal (_c_d_r _l__l).
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 _c_a_r's of l_list using
427: the function _e_q_u_a_l.
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: _d_e_l_q (and _d_r_e_m_o_v_e) are the same as _d_e_l_e_t_e except
439: that _e_q is used for comparison instead of _e_q_u_a_l.
440:
441:
442:
443:
444:
445:
446:
447:
448:
449:
450:
451: 9
452:
453: 9 Printed: January 31, 1984
454:
455:
456:
457:
458:
459:
460:
461: Data Structure Access 2-8
462:
463:
464:
465: ____________________________________________________
466:
467: ; note that you should use the value returned by _d_e_l_e_t_e or _d_e_l_q
468: ; and not assume that g_val will always show the deletions.
469: ; For example
470:
471: -> (_s_e_t_q _t_e_s_t '(_a _b _c _a _d _e))
472: (a b c a d e)
473: -> (_d_e_l_e_t_e '_a _t_e_s_t)
474: (b c d e) ; the value returned is what we would expect
475: -> _t_e_s_t
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 _c_o_p_y of l_l with all top level elements
486: _e_q_u_a_l to g_x removed. _r_e_m_q uses _e_q instead of
487: _e_q_u_a_l for comparisons.
488:
489: NOTE: remove does not modify its arguments like _d_e_l_e_t_e,
490: and _d_e_l_q 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: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) 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. _i_n_s_e_r_t
504: does binary search to determine where to insert
505: the new element.
506:
507:
508:
509:
510:
511:
512:
513:
514:
515:
516: 9
517:
518: 9 Printed: January 31, 1984
519:
520:
521:
522:
523:
524:
525:
526: Data 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: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) 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". _m_e_r_g_e 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 _e_q_u_a_l
547: occurrences of g_y at all levels in l_s.
548:
549: NOTE: If g_y is a symbol, _e_q will be used for comparis-
550: ons. The function _s_u_b_s_t does not modify l_s but
551: the function _d_s_u_b_s_t (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: -> (_s_u_b_s_t '(_a _b _c) '_x '(_x _y _z (_x _y _z) (_x _y _z)))
566: ((a b c) y z ((a b c) y z) ((a b c) y z))
567: -> (_l_s_u_b_s_t '(_a _b _c) '_x '(_x _y _z (_x _y _z) (_x _y _z)))
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: 9
582:
583: 9 Printed: January 31, 1984
584:
585:
586:
587:
588:
589:
590:
591: Data 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: (_s_u_b_p_a_i_r '(_a _c)' (_x _y) '(_a _b _c _d)) = (_x _b _y _d)
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 _c_d_r of the last list cell of l_arg_i is
615: changed to point to l_arg_i+_1.
616:
617:
618: ____________________________________________________
619:
620: ; _n_c_o_n_c is faster than _a_p_p_e_n_d because it doesn't allocate new list cells.
621: -> (_s_e_t_q _l_i_s_1 '(_a _b _c))
622: (a b c)
623: -> (_s_e_t_q _l_i_s_2 '(_d _e _f))
624: (d e f)
625: -> (_a_p_p_e_n_d _l_i_s_1 _l_i_s_2)
626: (a b c d e f)
627: -> _l_i_s_1
628: (a b c) ; note that lis1 has not been changed by _a_p_p_e_n_d
629: -> (_n_c_o_n_c _l_i_s_1 _l_i_s_2)
630: (a b c d e f) ; _n_c_o_n_c returns the same value as _a_p_p_e_n_d
631: -> _l_i_s_1
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: 9
647:
648: 9 Printed: January 31, 1984
649:
650:
651:
652:
653:
654:
655:
656: Data 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 _n_r_e_v_e_r_s_e does the reversal in place,
666: that is the list structure is modified.
667:
668: (nreconc 'l_arg 'g_arg)
669:
670: EQUIVALENT TO: (_n_c_o_n_c (_n_r_e_v_e_r_s_e '_l__a_r_g) '_g__a_r_g)
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: (_a_t_o_m '()) 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: 9
712:
713: 9 Printed: January 31, 1984
714:
715:
716:
717:
718:
719:
720:
721: Data 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: 9
777:
778: 9 Printed: January 31, 1984
779:
780:
781:
782:
783:
784:
785:
786: Data 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 _s_i_g_n_p simply returns nil if g_val
795: is not a number is probably the most important
796: reason that _s_i_g_n_p is used. The permitted values
797: for s_test and what they mean are given in this
798: table.
799:
800: 8 ____________________
801: s_test tested
802:
803: 8 ________________________________________
804: l g_val < 0
805: le g_val <_ 0
806: e g_val = 0
807: n g_val =/ 0
808: ge g_val >_ 0
809: g g_val > 0
810: 8 ____________________
811: 7 |7|7|7|7|7|7|7|7|
812:
813:
814:
815:
816:
817:
818:
819: |7|7|7|7|7|7|7|7|
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: _E_q 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 _e_q. The
838: only objects guaranteed to be _e_q are interned
839: symbols with the same print name. [Unless a sym-
840: bol is created in a special way (such as with
841: _u_c_o_n_c_a_t or _m_a_k_n_a_m) it will be interned.]
842:
843: (neq 'g_x 'g_y)
844:
845: RETURNS: t if g_x is not _e_q 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 _e_q_u_a_l if
854:
855: (1) they are _e_q.
856:
857: (2) they are both fixnums with the same value
858:
859:
860:
861:
862: 9 Printed: January 31, 1984
863:
864:
865:
866:
867:
868:
869:
870: Data 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: _e_q_u_a_l.
881:
882:
883: ____________________________________________________
884:
885: ; _e_q is much faster than _e_q_u_a_l, especially in compiled code,
886: ; however you cannot use _e_q to test for equality of numbers outside
887: ; of the range -1024 to 1023. _e_q_u_a_l will always work.
888: -> (_e_q _1_0_2_3 _1_0_2_3)
889: t
890: -> (_e_q _1_0_2_4 _1_0_2_4)
891: nil
892: -> (_e_q_u_a_l _1_0_2_4 _1_0_2_4)
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: _m_e_m_b_e_r tests for equality with _e_q_u_a_l, _m_e_m_q tests
914: for equality with _e_q.
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:
936: Data Structure Access 2-15
937:
938:
939: FRANZ LISP. They _e_v_a_l 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_i.
962:
963: NOTE: If no arguments are given, a symbol with a null
964: pname is returned. _c_o_n_c_a_t places the symbol
965: created on the oblist, the function _u_c_o_n_c_a_t does
966: the same thing but does not place the new symbol
967: on the oblist.
968:
969: EXAMPLE: (_c_o_n_c_a_t '_a_b_c (_a_d_d _3 _4) "_d_e_f") = abc7def
970:
971: (concatl 'l_arg)
972:
973: EQUIVALENT TO: (_a_p_p_l_y '_c_o_n_c_a_t '_l__a_r_g)
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 _c_o_n_c_a_t.
989:
990: NOTE: _i_m_p_l_o_d_e interns the symbol it creates, _m_a_k_n_a_m
991: does not.
992:
993:
994: Printed: January 31, 1984
995:
996:
997:
998:
999:
1000:
1001:
1002: Data 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 _e_q 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 _n_o_t check to see if s_arg is
1053: on the oblist or is referenced anywhere. Thus
1054: calling _r_e_m_a_t_o_m on an atom in the oblist may
1055: result in disaster when that atom cell is reused!
1056:
1057: 9
1058:
1059: 9 Printed: January 31, 1984
1060:
1061:
1062:
1063:
1064:
1065:
1066:
1067: Data 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 _m_a_k_u_n_b_o_u_n_d.
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: _e_v_a_l, 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: 9
1123:
1124: 9 Printed: January 31, 1984
1125:
1126:
1127:
1128:
1129:
1130:
1131:
1132: Data 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_t_h 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: _g_e_t_c_h_a_r and _n_t_h_c_h_a_r return a symbol with a single
1144: character print name, _g_e_t_c_h_a_r_n 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_t_h 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_t_h character from the end.
1157: If x_index is out of bounds, nil is returned.
1158:
1159: NOTE: _s_u_b_s_t_r_i_n_g returns a list of symbols, _s_u_b_s_t_r_i_n_g_n
1160: returns a list of fixnums. If _s_u_b_s_t_r_i_n_g_n is
1161: given a 0 x_length argument then a single fixnum
1162: which is the x_index_t_h 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_i.
1180:
1181: SIDE EFFECT: each s_atm_i is set to have the value
1182: g_val_i.
1183:
1184: NOTE: _s_e_t evaluates all of its arguments, _s_e_t_q does not
1185: evaluate the s_atm_i.
1186:
1187: 9
1188:
1189: 9 Printed: January 31, 1984
1190:
1191:
1192:
1193:
1194:
1195:
1196:
1197: Data 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 _s_e_t_q if all the
1205: sl_pattern_i are symbols. If sl_pattern_i
1206: is a list then it is a template which
1207: should have the same structure as g_exp_i
1208: The symbols in sl_pattern are assigned to
1209: the corresponding parts of g_exp. (See
1210: also _s_e_t_f )
1211:
1212: EXAMPLE: (_d_e_s_e_t_q (_a _b (_c . _d)) '(_1 _2 (_3 _4 _5)))
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 _a_e_x_p_l_o_d_e and _e_x_p_l_o_d_e return a list
1245: of characters which _p_r_i_n_t would use to print the
1246: argument. These characters include all necessary
1247: escape characters. Functions _a_e_x_p_l_o_d_e_c and
1248: _e_x_p_l_o_d_e_c return a list of characters which _p_a_t_o_m
1249: would use to print the argument (i.e. no escape
1250: characters). Functions _a_e_x_p_l_o_d_e_n and _e_x_p_l_o_d_e_n
1251: are similar to _a_e_x_p_l_o_d_e_c and _e_x_p_l_o_d_e_c 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:
1263: Data Structure Access 2-20
1264:
1265:
1266: returned.
1267:
1268:
1269: ____________________________________________________
1270:
1271: -> (_s_e_t_q _x '|_q_u_o_t_e _t_h_i_s _\| _o_k?|)
1272: |quote this \| ok?|
1273: -> (_e_x_p_l_o_d_e _x)
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: -> (_e_x_p_l_o_d_e_c _x)
1280: (q u o t e | | t h i s | | |\|| | | o k ?)
1281: -> (_e_x_p_l_o_d_e_n _x)
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:
1329: Data 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: 9
1385:
1386: 9 Printed: January 31, 1984
1387:
1388:
1389:
1390:
1391:
1392:
1393:
1394: Data 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 _c_a_r 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: 9
1450:
1451: 9 Printed: January 31, 1984
1452:
1453:
1454:
1455:
1456:
1457:
1458:
1459: Data 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_n)
1480: (array s_name s_type x_dim1 ... x_dim_n)
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_i.
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: *_a_r_r_a_y evaluates its arguments, _a_r_r_a_y does not.
1502:
1503:
1504:
1505: 2.5.2. array predicate
1506:
1507:
1508:
1509:
1510:
1511:
1512:
1513:
1514: 9
1515:
1516: 9 Printed: January 31, 1984
1517:
1518:
1519:
1520:
1521:
1522:
1523:
1524: Data 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_t_h element of the array object
1548: a_name. x_ind of zero accesses the first ele-
1549: ment.
1550:
1551: NOTE: _a_r_r_a_y_r_e_f 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 _a_r_r_a_y_c_a_l_l 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: 9
1580:
1581: 9 Printed: January 31, 1984
1582:
1583:
1584:
1585:
1586:
1587:
1588:
1589: Data 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: -> (_a_r_r_a_y _e_r_n_i_e _t _3 _4)
1604: array[12]
1605:
1606: ; the array header is stored in the function definition slot of the
1607: ; symbol ernie
1608: -> (_a_r_r_a_y_p (_g_e_t_d '_e_r_n_i_e))
1609: t
1610: -> (_a_r_r_a_y_d_i_m_s (_g_e_t_d '_e_r_n_i_e))
1611: (t 3 4)
1612:
1613: ; store in ernie[2][2] the list (test list)
1614: -> (_s_t_o_r_e (_e_r_n_i_e _2 _2) '(_t_e_s_t _l_i_s_t))
1615: (test list)
1616:
1617: ; check to see if it is there
1618: -> (_e_r_n_i_e _2 _2)
1619: (test list)
1620:
1621: ; now use the low level function _a_r_r_a_y_r_e_f 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: -> (_a_r_r_a_y_r_e_f (_g_e_t_d '_e_r_n_i_e) _1_0)
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: 9
1645:
1646: 9 Printed: January 31, 1984
1647:
1648:
1649:
1650:
1651:
1652:
1653:
1654: Data 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 (*_m_a_k_h_u_n_k and
1702: *_r_p_l_a_c_x) which will overwrite the distinguished sym-
1703: bol.
1704:
1705:
1706:
1707:
1708:
1709: 9
1710:
1711: 9 Printed: January 31, 1984
1712:
1713:
1714:
1715:
1716:
1717:
1718:
1719: Data Structure Access 2-27
1720:
1721:
1722: 2.6.1. hunk creation
1723:
1724: (hunk 'g_val1 ['g_val2 ... 'g_val_n])
1725:
1726: RETURNS: a hunk of length n whose elements are initial-
1727: ized to the g_val_i.
1728:
1729: NOTE: the maximum size of a hunk is 128.
1730:
1731: EXAMPLE: (_h_u_n_k _4 '_s_h_a_r_p '_k_e_y_s) = {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: (_l_e_n_g_t_h '_x_l__a_r_g) initialized to the elements
1739: in xl_arg.
1740:
1741: NOTE: (_m_a_k_h_u_n_k '(_a _b _c)) is equivalent to
1742: (_h_u_n_k '_a '_b '_c).
1743:
1744: EXAMPLE: (_m_a_k_h_u_n_k _4) = {_n_i_l _n_i_l _n_i_l _n_i_l}
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 _h_u_n_k
1751: and _m_a_k_h_u_n_k 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: 9
1775:
1776: 9 Printed: January 31, 1984
1777:
1778:
1779:
1780:
1781:
1782:
1783:
1784: Data 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: _r_p_l_a_c_x will not modify one of the distinguished
1796: (EMPTY) elements whereas *_r_p_l_a_c_x will.
1797:
1798: (hunksize 'h_arg)
1799:
1800: RETURNS: the size of the hunk h_arg.
1801:
1802: EXAMPLE: (_h_u_n_k_s_i_z_e (_h_u_n_k _1 _2 _3)) = 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:
1850: Data 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: _c_a_r is _e_q_u_a_l (with _a_s_s_o_c) or _e_q (with _a_s_s_q) to
1860: g_arg1.
1861:
1862: NOTE: Usually l_arg2 has an _a-_l_i_s_t structure and g_arg1
1863: acts as key.
1864:
1865: (sassoc 'g_arg1 'l_arg2 'sl_func)
1866:
1867: RETURNS: the result of
1868: (_c_o_n_d ((_a_s_s_o_c '_g__a_r_g '_l__a_r_g_2) (_a_p_p_l_y '_s_l__f_u_n_c _n_i_l)))
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: (_c_o_n_d ((_a_s_s_q '_g__a_r_g '_l__a_r_g_2) (_a_p_p_l_y '_s_l__f_u_n_c _n_i_l)))
1876:
1877: NOTE: sassq is written as a macro.
1878:
1879:
1880:
1881: ____________________________________________________
1882:
1883: ; _a_s_s_o_c or _a_s_s_q 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: -> (_s_e_t_q _a_l_i_s_t '((_a_l_p_h_a . _a) ( (_c_o_m_p_l_e_x _k_e_y) . _b) (_j_u_n_k . _x)))
1888: ((alpha . a) ((complex key) . b) (junk . x))
1889:
1890: ; we should use _a_s_s_q when the key is an atom
1891: -> (_a_s_s_q '_a_l_p_h_a _a_l_i_s_t)
1892: (alpha . a)
1893:
1894: ; but it may not work when the key is a list
1895: -> (_a_s_s_q '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
1896: nil
1897:
1898: ; however _a_s_s_o_c will always work
1899: -> (_a_s_s_o_c '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
1900: ((complex key) . b)
1901: ____________________________________________________
1902:
1903:
1904:
1905: 9
1906:
1907: 9 Printed: January 31, 1984
1908:
1909:
1910:
1911:
1912:
1913:
1914:
1915: Data Structure Access 2-30
1916:
1917:
1918: (sublis 'l_alst 'l_exp)
1919:
1920: WHERE: l_alst is an _a-_l_i_s_t.
1921:
1922: RETURNS: the list l_exp with every occurrence of key_i
1923: replaced by val_i.
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. _g_e_t searches a disembodied
1960: property list by starting at its _c_d_r, and compar-
1961: ing every other element with g_ind, using _e_q.
1962:
1963:
1964:
1965:
1966:
1967:
1968:
1969:
1970: 9
1971:
1972: 9 Printed: January 31, 1984
1973:
1974:
1975:
1976:
1977:
1978:
1979:
1980: Data 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: _p_u_t_p_r_o_p evaluates it arguments, _d_e_f_p_r_o_p does not.
2004: ls_name may be a disembodied property list, see
2005: _g_e_t.
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: _g_e_t.
2020:
2021:
2022:
2023:
2024:
2025:
2026:
2027:
2028:
2029:
2030:
2031:
2032:
2033:
2034:
2035: 9
2036:
2037: 9 Printed: January 31, 1984
2038:
2039:
2040:
2041:
2042:
2043:
2044:
2045: Data Structure Access 2-32
2046:
2047:
2048:
2049: ____________________________________________________
2050:
2051: -> (_p_u_t_p_r_o_p '_x_l_a_t_e '_a '_a_l_p_h_a)
2052: a
2053: -> (_p_u_t_p_r_o_p '_x_l_a_t_e '_b '_b_e_t_a)
2054: b
2055: -> (_p_l_i_s_t '_x_l_a_t_e)
2056: (alpha a beta b)
2057: -> (_g_e_t '_x_l_a_t_e '_a_l_p_h_a)
2058: a
2059: ; use of a disembodied property list:
2060: -> (_g_e_t '(_n_i_l _f_a_t_e_m_a_n _r_j_f _s_k_l_o_w_e_r _k_l_s _f_o_d_e_r_a_r_o _j_k_f) '_s_k_l_o_w_e_r)
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 _c_a_r points to a
2074: list of the elements added with _t_c_o_n_c or _l_c_o_n_c and
2075: whose _c_d_r points to the last list cell of the list
2076: pointed to by the _c_a_r.
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: 9
2101:
2102: 9 Printed: January 31, 1984
2103:
2104:
2105:
2106:
2107:
2108:
2109:
2110: Data Structure Access 2-33
2111:
2112:
2113:
2114: ____________________________________________________
2115:
2116: ; A _t_c_o_n_c structure can be initialized in two ways.
2117: ; nil can be given to _t_c_o_n_c in which case _t_c_o_n_c will generate
2118: ; a _t_c_o_n_c structure.
2119:
2120: ->(_s_e_t_q _f_o_o (_t_c_o_n_c _n_i_l _1))
2121: ((1) 1)
2122:
2123: ; Since _t_c_o_n_c destructively adds to
2124: ; the list, you can now add to foo without using _s_e_t_q again.
2125:
2126: ->(_t_c_o_n_c _f_o_o _2)
2127: ((1 2) 2)
2128: ->_f_o_o
2129: ((1 2) 2)
2130:
2131: ; Another way to create a null _t_c_o_n_c structure
2132: ; is to use (_n_c_o_n_s _n_i_l).
2133:
2134: ->(_s_e_t_q _f_o_o (_n_c_o_n_s _n_i_l))
2135: (nil)
2136: ->(_t_c_o_n_c _f_o_o _1)
2137: ((1) 1)
2138:
2139: ; now see what _l_c_o_n_c can do
2140: -> (_l_c_o_n_c _f_o_o _n_i_l)
2141: ((1) 1) ; no change
2142: -> (_l_c_o_n_c _f_o_o '(_2 _3 _4))
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: 9
2166:
2167: 9 Printed: January 31, 1984
2168:
2169:
2170:
2171:
2172:
2173:
2174:
2175: Data 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 _f_c_l_o_s_u_r_e-_a_l_i_s_t
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: 9
2231:
2232: 9 Printed: January 31, 1984
2233:
2234:
2235:
2236:
2237:
2238:
2239:
2240: Data 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: _b_c_d_a_d returns nil.
2249:
2250: (copy 'g_arg)
2251:
2252: RETURNS: A structure _e_q_u_a_l 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_i. It then
2273: creates a binary object whose entry field points
2274: to s_entry_i and whose discipline is
2275: st_discipline_i. This binary object is stored in
2276: the function field of s_binder_i. If
2277: st_discipline_i is nil, then "subroutine" is used
2278: by default. This is especially useful for _c_f_a_s_l
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 _c_o_n_d and _d_o,
2288: thus it misses many macro expansions.
2289:
2290:
2291:
2292:
2293:
2294:
2295: 9
2296:
2297: 9 Printed: January 31, 1984
2298:
2299:
2300:
2301:
2302:
2303:
2304:
2305: Data 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: (_l_i_s_t (_q_u_o_t_e _q_u_o_t_e) _g__a_r_g).
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 _r_e_p_l_a_c_e is dependent on the
2331: type of the g_arg_i although one will
2332: notice a similarity in the effects. To
2333: understand what _r_e_p_l_a_c_e 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 _r_e_p_l_a_c_e 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 (_s_e_t_q _y _x), then both x and y
2358: will point to the same box. If you now
2359: (_r_e_p_l_a_c_e _x _1_2_3_4_5), 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:
2371: Data 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: _c_o_p_y_i_n_t* for a way around this problem).
2383:
2384: For the other valid types, the effect of
2385: _r_e_p_l_a_c_e 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: (_r_e_p_l_a_c_e _x _y) is the same as
2391: (_r_p_l_a_c_a _x (_c_a_r _y)) and (_r_p_l_a_c_d _x (_c_d_r _y)).
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: _s_e_t_f 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. _s_e_t_f returns g_value.
2411: (Compare to _d_e_s_e_t_q )
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: 9
2427:
2428: 9 Printed: January 31, 1984
2429:
2430:
2431:
2432:
2433:
2434:
2435:
2436: Data 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: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) 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: _c_a_r'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 _s_o_r_t, 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: 9
2492:
2493: 9 Printed: January 31, 1984
2494:
2495:
2496:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.