![[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] / 42BSD / ucb / lisp / lisplib / manual|
Return to ch2.r CVS log | Up to [CSRG BSD Unix] / 42BSD / 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: August 5, 1983
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: August 5, 1983
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.
209:
210: (listp 'g_arg)
211:
212: RETURNS: t iff g_arg is a list object or nil.
213:
214: (tailp 'l_x 'l_y)
215:
216: RETURNS: l_x, if a list cell _e_q to l_x is found by
217: _c_d_ring down l_y zero or more times, nil other-
218: wise.
219:
220:
221: ____________________________________________________
222:
223: -> (_s_e_t_q _x '(_a _b _c _d) _y (_c_d_d_r _x))
224: (c d)
225: -> (_a_n_d (_d_t_p_r _x) (_l_i_s_t_p _x)) ; x and y are dtprs and lists
226: t
227: -> (_d_t_p_r '()) ; () is the same as nil and is not a dtpr
228: nil
229: -> (_l_i_s_t_p '()) ; however it is a list
230: t
231: -> (_t_a_i_l_p _y _x)
232: (c d)
233: ____________________________________________________
234:
235:
236:
237:
238: (length 'l_arg)
239:
240: RETURNS: the number of elements in the top level of
241: list l_arg.
242:
243:
244:
245: 2.1.3. list accessing
246:
247:
248:
249:
250:
251:
252:
253:
254:
255:
256: 9
257:
258: 9 Printed: August 5, 1983
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 seems to bother few.
276:
277: (c..r 'lh_arg)
278:
279: WHERE: the .. represents any positive number of a's
280: and d's.
281:
282: RETURNS: the result of accessing the list structure in
283: the way determined by the function name. The
284: a's and d's are read from right to left, a d
285: directing the access down the cdr part of the
286: list cell and an a down the car part.
287:
288: NOTE: lh_arg may also be nil, and it is guaranteed that
289: the car and cdr of nil is nil. If lh_arg is a
290: hunk, then (_c_a_r '_l_h__a_r_g) is the same as
291: (_c_x_r _1 '_l_h__a_r_g) and (_c_d_r '_l_h__a_r_g) is the same as
292: (_c_x_r _0 '_l_h__a_r_g).
293: It is generally hard to read and understand the
294: context of functions with large strings of a's
295: and d's, but these functions are supported by
296: rapid accessing and open-compiling (see Chapter
297: 12).
298:
299: (nth 'x_index 'l_list)
300:
301: RETURNS: the nth element of l_list, assuming zero-based
302: index. Thus (nth 0 l_list) is the same as
303: (car l_list). _n_t_h is both a function, and a
304: compiler macro, so that more efficient code
305: might be generated than for _n_t_h_e_l_e_m (described
306: below).
307:
308: NOTE: If x_arg1 is non-positive or greater than the
309: length of the list, nil is returned.
310:
311:
312:
313:
314:
315:
316:
317:
318:
319:
320:
321: 9
322:
323: 9 Printed: August 5, 1983
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: August 5, 1983
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: August 5, 1983
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: August 5, 1983
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: August 5, 1983
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: August 5, 1983
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: the name of this function is a throwback to the
698: PDP-11 Lisp system.
699:
700: (bigp 'g_arg)
701:
702: RETURNS: t iff g_arg is a bignum.
703:
704:
705:
706:
707:
708:
709:
710:
711: 9
712:
713: 9 Printed: August 5, 1983
714:
715:
716:
717:
718:
719:
720:
721: Data Structure Access 2-12
722:
723:
724: (dtpr 'g_arg)
725:
726: RETURNS: t iff g_arg is a list cell.
727:
728: NOTE: that (dtpr '()) is nil.
729:
730: (hunkp 'g_arg)
731:
732: RETURNS: t iff g_arg is a hunk.
733:
734: (listp 'g_arg)
735:
736: RETURNS: t iff g_arg is a list object or nil.
737:
738: (stringp 'g_arg)
739:
740: RETURNS: t iff g_arg is a string.
741:
742: (symbolp 'g_arg)
743:
744: RETURNS: t iff g_arg is a symbol.
745:
746: (valuep 'g_arg)
747:
748: RETURNS: t iff g_arg is a value cell
749:
750: (vectorp 'v_vector)
751:
752: RETURNS: t iff the argument is a vector.
753:
754: (vectorip 'v_vector)
755:
756: RETURNS: t iff the argument is an immediate-vector.
757:
758: (type 'g_arg)
759: (typep 'g_arg)
760:
761: RETURNS: a symbol whose pname describes the type of
762: g_arg.
763:
764: (signp s_test 'g_val)
765:
766: RETURNS: t iff g_val is a number and the given test
767: s_test on g_val returns true.
768:
769: NOTE: The fact that _s_i_g_n_p simply returns nil if g_val
770: is not a number is probably the most important
771: reason that _s_i_g_n_p is used. The permitted values
772: for s_test and what they mean are given in this
773: table.
774:
775: 9
776:
777:
778: 9 Printed: August 5, 1983
779:
780:
781:
782:
783:
784:
785:
786: Data Structure Access 2-13
787:
788:
789: 8 ____________________
790: s_test tested
791:
792: 8 ________________________________________
793: l g_val < 0
794: le g_val <_ 0
795: e g_val = 0
796: n g_val =/ 0
797: ge g_val >_ 0
798: g g_val > 0
799: 8 ____________________
800: 7 |7|7|7|7|7|7|7|7|
801:
802:
803:
804:
805:
806:
807:
808: |7|7|7|7|7|7|7|7|
809:
810:
811:
812:
813:
814:
815:
816:
817:
818:
819: (eq 'g_arg1 'g_arg2)
820:
821: RETURNS: t if g_arg1 and g_arg2 are the exact same lisp
822: object.
823:
824: NOTE: _E_q simply tests if g_arg1 and g_arg2 are located
825: in the exact same place in memory. Lisp objects
826: which print the same are not necessarily _e_q. The
827: only objects guaranteed to be _e_q are interned
828: symbols with the same print name. [Unless a sym-
829: bol is created in a special way (such as with
830: _u_c_o_n_c_a_t or _m_a_k_n_a_m) it will be interned.]
831:
832: (neq 'g_x 'g_y)
833:
834: RETURNS: t if g_x is not _e_q to g_y, otherwise nil.
835:
836: (equal 'g_arg1 'g_arg2)
837: (eqstr 'g_arg1 'g_arg2)
838:
839: RETURNS: t iff g_arg1 and g_arg2 have the same struc-
840: ture as described below.
841:
842: NOTE: g_arg and g_arg2 are _e_q_u_a_l if
843:
844: (1) they are _e_q.
845:
846: (2) they are both fixnums with the same value
847:
848: (3) they are both flonums with the same value
849:
850: (4) they are both bignums with the same value
851:
852: (5) they are both strings and are identical.
853:
854: (6) they are both lists and their cars and cdrs are
855: _e_q_u_a_l.
856:
857:
858:
859:
860:
861:
862: 9 Printed: August 5, 1983
863:
864:
865:
866:
867:
868:
869:
870: Data Structure Access 2-14
871:
872:
873:
874: ____________________________________________________
875:
876: ; _e_q is much faster than _e_q_u_a_l, especially in compiled code,
877: ; however you cannot use _e_q to test for equality of numbers outside
878: ; of the range -1024 to 1023. _e_q_u_a_l will always work.
879: -> (_e_q _1_0_2_3 _1_0_2_3)
880: t
881: -> (_e_q _1_0_2_4 _1_0_2_4)
882: nil
883: -> (_e_q_u_a_l _1_0_2_4 _1_0_2_4)
884: t
885: ____________________________________________________
886:
887:
888:
889:
890:
891: (not 'g_arg)
892: (null 'g_arg)
893:
894: RETURNS: t iff g_arg is nil.
895:
896:
897: (member 'g_arg1 'l_arg2)
898: (memq 'g_arg1 'l_arg2)
899:
900: RETURNS: that part of the l_arg2 beginning with the
901: first occurrence of g_arg1. If g_arg1 is not
902: in the top level of l_arg2, nil is returned.
903:
904: NOTE: _m_e_m_b_e_r tests for equality with _e_q_u_a_l, _m_e_m_q tests
905: for equality with _e_q.
906:
907:
908:
909:
910: 2.3. Symbols and Strings
911:
912: In many of the following functions the distinc-
913: tion between symbols and strings is somewhat blurred.
914: To remind ourselves of the difference, a string is a
915: null terminated sequence of characters, stored as com-
916: pactly as possible. Strings are used as constants in
917: FRANZ LISP. They _e_v_a_l to themselves. A symbol has
918: additional structure: a value, property list, function
919: binding, as well as its external representation (or
920: print-name). If a symbol is given to one of the
921: string manipulation functions below, its print name
922: will be used.
923:
924: Another popular way to represent strings in Lisp
925: is as a list of fixnums which represent characters.
926:
927:
928: Printed: August 5, 1983
929:
930:
931:
932:
933:
934:
935:
936: Data Structure Access 2-15
937:
938:
939: The suffix 'n' to a string manipulation function indi-
940: cates that it returns a string in this form.
941:
942:
943:
944: 2.3.1. symbol and string creation
945:
946: (concat ['stn_arg1 ... ])
947: (uconcat ['stn_arg1 ... ])
948:
949: RETURNS: a symbol whose print name is the result of
950: concatenating the print names, string charac-
951: ters or numerical representations of the
952: sn_arg_i.
953:
954: NOTE: If no arguments are given, a symbol with a null
955: pname is returned. _c_o_n_c_a_t places the symbol
956: created on the oblist, the function _u_c_o_n_c_a_t does
957: the same thing but does not place the new symbol
958: on the oblist.
959:
960: EXAMPLE: (_c_o_n_c_a_t '_a_b_c (_a_d_d _3 _4) "_d_e_f") = abc7def
961:
962: (concatl 'l_arg)
963:
964: EQUIVALENT TO: (_a_p_p_l_y '_c_o_n_c_a_t '_l__a_r_g)
965:
966:
967: (implode 'l_arg)
968: (maknam 'l_arg)
969:
970: WHERE: l_arg is a list of symbols, strings and small
971: fixnums.
972:
973: RETURNS: The symbol whose print name is the result of
974: concatenating the first characters of the
975: print names of the symbols and strings in the
976: list. Any fixnums are converted to the
977: equivalent ascii character. In order to con-
978: catenate entire strings or print names, use
979: the function _c_o_n_c_a_t.
980:
981: NOTE: _i_m_p_l_o_d_e interns the symbol it creates, _m_a_k_n_a_m
982: does not.
983:
984:
985:
986:
987:
988:
989:
990:
991: 9
992:
993: 9 Printed: August 5, 1983
994:
995:
996:
997:
998:
999:
1000:
1001: Data Structure Access 2-16
1002:
1003:
1004: (gensym ['s_leader])
1005:
1006: RETURNS: a new uninterned atom beginning with the first
1007: character of s_leader's pname, or beginning
1008: with g if s_leader is not given.
1009:
1010: NOTE: The symbol looks like x0nnnnn where x is
1011: s_leader's first character and nnnnn is the
1012: number of times you have called gensym.
1013:
1014: (copysymbol 's_arg 'g_pred)
1015:
1016: RETURNS: an uninterned symbol with the same print name
1017: as s_arg. If g_pred is non nil, then the
1018: value, function binding and property list of
1019: the new symbol are made _e_q to those of s_arg.
1020:
1021:
1022: (ascii 'x_charnum)
1023:
1024: WHERE: x_charnum is between 0 and 255.
1025:
1026: RETURNS: a symbol whose print name is the single char-
1027: acter whose fixnum representation is
1028: x_charnum.
1029:
1030:
1031: (intern 's_arg)
1032:
1033: RETURNS: s_arg
1034:
1035: SIDE EFFECT: s_arg is put on the oblist if it is not
1036: already there.
1037:
1038: (remob 's_symbol)
1039:
1040: RETURNS: s_symbol
1041:
1042: SIDE EFFECT: s_symbol is removed from the oblist.
1043:
1044: (rematom 's_arg)
1045:
1046: RETURNS: t if s_arg is indeed an atom.
1047:
1048: SIDE EFFECT: s_arg is put on the free atoms list,
1049: effectively reclaiming an atom cell.
1050:
1051: NOTE: This function does _n_o_t check to see if s_arg is
1052: on the oblist or is referenced anywhere. Thus
1053: calling _r_e_m_a_t_o_m on an atom in the oblist may
1054: result in disaster when that atom cell is reused!
1055:
1056: 9
1057:
1058: 9 Printed: August 5, 1983
1059:
1060:
1061:
1062:
1063:
1064:
1065:
1066: Data Structure Access 2-17
1067:
1068:
1069: 2.3.2. string and symbol predicates
1070:
1071: (boundp 's_name)
1072:
1073: RETURNS: nil if s_name is unbound, that is it has
1074: never be given a value. If x_name has the
1075: value g_val, then (nil . g_val) is returned.
1076:
1077: (alphalessp 'st_arg1 'st_arg2)
1078:
1079: RETURNS: t iff the `name' of st_arg1 is alphabetically
1080: less than the name of st_arg2. If st_arg is a
1081: symbol then its `name' is its print name. If
1082: st_arg is a string, then its `name' is the
1083: string itself.
1084:
1085:
1086:
1087: 2.3.3. symbol and string accessing
1088:
1089: (symeval 's_arg)
1090:
1091: RETURNS: the value of symbol s_arg.
1092:
1093: NOTE: It is illegal to ask for the value of an unbound
1094: symbol. This function has the same effect as
1095: _e_v_a_l, but compiles into much more efficient code.
1096:
1097: (get_pname 's_arg)
1098:
1099: RETURNS: the string which is the print name of s_arg.
1100:
1101: (plist 's_arg)
1102:
1103: RETURNS: the property list of s_arg.
1104:
1105: (getd 's_arg)
1106:
1107: RETURNS: the function definition of s_arg or nil if
1108: there is no function definition.
1109:
1110: NOTE: the function definition may turn out to be an
1111: array header.
1112:
1113:
1114:
1115:
1116:
1117:
1118:
1119:
1120:
1121: 9
1122:
1123: 9 Printed: August 5, 1983
1124:
1125:
1126:
1127:
1128:
1129:
1130:
1131: Data Structure Access 2-18
1132:
1133:
1134: (getchar 's_arg 'x_index)
1135: (nthchar 's_arg 'x_index)
1136: (getcharn 's_arg 'x_index)
1137:
1138: RETURNS: the x_index_t_h character of the print name of
1139: s_arg or nil if x_index is less than 1 or
1140: greater than the length of s_arg's print name.
1141:
1142: NOTE: _g_e_t_c_h_a_r and _n_t_h_c_h_a_r return a symbol with a single
1143: character print name, _g_e_t_c_h_a_r_n returns the fixnum
1144: representation of the character.
1145:
1146: (substring 'st_string 'x_index ['x_length])
1147: (substringn 'st_string 'x_index ['x_length])
1148:
1149: RETURNS: a string of length at most x_length starting
1150: at x_index_t_h character in the string.
1151:
1152: NOTE: If x_length is not given, all of the characters
1153: for x_index to the end of the string are
1154: returned. If x_index is negative the string
1155: begins at the x_index_t_h character from the end.
1156: If x_index is out of bounds, nil is returned.
1157:
1158: 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
1159: returns a list of fixnums. If _s_u_b_s_t_r_i_n_g_n is
1160: given a 0 x_length argument then a single fixnum
1161: which is the x_index_t_h character is returned.
1162:
1163:
1164:
1165: 2.3.4. symbol and string manipulation
1166:
1167: (set 's_arg1 'g_arg2)
1168:
1169: RETURNS: g_arg2.
1170:
1171: SIDE EFFECT: the value of s_arg1 is set to g_arg2.
1172:
1173: (setq s_atm1 'g_val1 [ s_atm2 'g_val2 ... ... ])
1174:
1175: WHERE: the arguments are pairs of atom names and
1176: expressions.
1177:
1178: RETURNS: the last g_val_i.
1179:
1180: SIDE EFFECT: each s_atm_i is set to have the value
1181: g_val_i.
1182:
1183: NOTE: _s_e_t evaluates all of its arguments, _s_e_t_q does not
1184: evaluate the s_atm_i.
1185:
1186: 9
1187:
1188: 9 Printed: August 5, 1983
1189:
1190:
1191:
1192:
1193:
1194:
1195:
1196: Data Structure Access 2-19
1197:
1198:
1199: (desetq sl_pattern1 'g_exp1 [... ...])
1200:
1201: RETURNS: g_expn
1202:
1203: SIDE EFFECT: This acts just like _s_e_t_q if all the
1204: sl_pattern_i are symbols. If sl_pattern_i
1205: is a list then it is a template which
1206: should have the same structure as g_exp_i
1207: The symbols in sl_pattern are assigned to
1208: the corresponding parts of g_exp.
1209:
1210: EXAMPLE: (_d_e_s_e_t_q (_a _b (_c . _d)) '(_1 _2 (_3 _4 _5)))
1211: sets a to 1, b to 2, c to 3, and d to (4 5).
1212:
1213:
1214: (setplist 's_atm 'l_plist)
1215:
1216: RETURNS: l_plist.
1217:
1218: SIDE EFFECT: the property list of s_atm is set to
1219: l_plist.
1220:
1221: (makunbound 's_arg)
1222:
1223: RETURNS: s_arg
1224:
1225: SIDE EFFECT: the value of s_arg is made `unbound'. If
1226: the interpreter attempts to evaluate s_arg
1227: before it is again given a value, an
1228: unbound variable error will occur.
1229:
1230: (aexplode 's_arg)
1231: (explode 'g_arg)
1232: (aexplodec 's_arg)
1233: (explodec 'g_arg)
1234: (aexploden 's_arg)
1235: (exploden 'g_arg)
1236:
1237: RETURNS: a list of the characters used to print out
1238: s_arg or g_arg.
1239:
1240: NOTE: The functions beginning with 'a' are internal
1241: functions which are limited to symbol arguments.
1242: The functions _a_e_x_p_l_o_d_e and _e_x_p_l_o_d_e return a list
1243: of characters which _p_r_i_n_t would use to print the
1244: argument. These characters include all necessary
1245: escape characters. Functions _a_e_x_p_l_o_d_e_c and
1246: _e_x_p_l_o_d_e_c return a list of characters which _p_a_t_o_m
1247: would use to print the argument (i.e. no escape
1248: characters). Functions _a_e_x_p_l_o_d_e_n and _e_x_p_l_o_d_e_n
1249: are similar to _a_e_x_p_l_o_d_e_c and _e_x_p_l_o_d_e_c except that
1250: a list of fixnum equivalents of characters are
1251: returned.
1252:
1253:
1254: Printed: August 5, 1983
1255:
1256:
1257:
1258:
1259:
1260:
1261:
1262: Data Structure Access 2-20
1263:
1264:
1265:
1266: ____________________________________________________
1267:
1268: -> (_s_e_t_q _x '|_q_u_o_t_e _t_h_i_s _\| _o_k?|)
1269: |quote this \| ok?|
1270: -> (_e_x_p_l_o_d_e _x)
1271: (q u o t e |\\| | | t h i s |\\| | | |\\| |\|| |\\| | | o k ?)
1272: ; note that |\\| just means the single character: backslash.
1273: ; and |\|| just means the single character: vertical bar
1274: ; and | | means the single character: space
1275:
1276: -> (_e_x_p_l_o_d_e_c _x)
1277: (q u o t e | | t h i s | | |\|| | | o k ?)
1278: -> (_e_x_p_l_o_d_e_n _x)
1279: (113 117 111 116 101 32 116 104 105 115 32 124 32 111 107 63)
1280: ____________________________________________________
1281:
1282:
1283:
1284:
1285:
1286:
1287: 2.4. Vectors
1288:
1289: See Chapter 9 for a discussion of vectors. They
1290: are intermediate in efficiency between arrays and
1291: hunks.
1292:
1293:
1294:
1295: 2.4.1. vector creation
1296:
1297: (new-vector 'x_size ['g_fill ['g_prop]])
1298:
1299: RETURNS: A vector of length x_size. Each data entry is
1300: initialized to g_fill, or to nil, if the argu-
1301: ment g_fill is not present. The vector's pro-
1302: perty is set to g_prop, or to nil, by default.
1303:
1304: (new-vectori-byte 'x_size ['g_fill ['g_prop]])
1305: (new-vectori-word 'x_size ['g_fill ['g_prop]])
1306: (new-vectori-long 'x_size ['g_fill ['g_prop]])
1307:
1308: RETURNS: A vectori with x_size elements in it. The
1309: actual memory requirement is two long words +
1310: x_size*(n bytes), where n is 1 for new-
1311: vector-byte, 2 for new-vector-word, or 4 for
1312: new-vectori-long. Each data entry is initial-
1313: ized to g_fill, or to zero, if the argument
1314: g_fill is not present. The vector's property
1315: is set to g_prop, or nil, by default.
1316:
1317: 9
1318:
1319: 9 Printed: August 5, 1983
1320:
1321:
1322:
1323:
1324:
1325:
1326:
1327: Data Structure Access 2-21
1328:
1329:
1330: Vectors may be created by specifying multiple initial
1331: values:
1332:
1333: (vector ['g_val0 'g_val1 ...])
1334:
1335: RETURNS: a vector, with as many data elements as there
1336: are arguments. It is quite possible to have a
1337: vector with no data elements. The vector's
1338: property will be null.
1339:
1340: (vectori-byte ['x_val0 'x_val2 ...])
1341: (vectori-word ['x_val0 'x_val2 ...])
1342: (vectori-long ['x_val0 'x_val2 ...])
1343:
1344: RETURNS: a vectori, with as many data elements as there
1345: are arguments. The arguments are required to
1346: be fixnums. Only the low order byte or word
1347: is used in the case of vectori-byte and
1348: vectori-word. The vector's property will be
1349: null.
1350:
1351:
1352:
1353: 2.4.2. vector reference
1354:
1355: (vref 'v_vect 'x_index)
1356: (vrefi-byte 'V_vect 'x_bindex)
1357: (vrefi-word 'V_vect 'x_windex)
1358: (vrefi-long 'V_vect 'x_lindex)
1359:
1360: RETURNS: the desired data element from a vector. The
1361: indices must be fixnums. Indexing is zero-
1362: based. The vrefi functions sign extend the
1363: data.
1364:
1365: (vprop 'Vv_vect)
1366:
1367: RETURNS: The Lisp property associated with a vector.
1368:
1369: (vget 'Vv_vect 'g_ind)
1370:
1371: RETURNS: The value stored under g_ind if the Lisp pro-
1372: perty associated with 'Vv_vect is a disembo-
1373: died property list.
1374:
1375:
1376:
1377:
1378:
1379:
1380:
1381:
1382: 9
1383:
1384: 9 Printed: August 5, 1983
1385:
1386:
1387:
1388:
1389:
1390:
1391:
1392: Data Structure Access 2-22
1393:
1394:
1395: (vsize 'Vv_vect)
1396: (vsize-byte 'V_vect)
1397: (vsize-word 'V_vect)
1398:
1399: RETURNS: the number of data elements in the vector.
1400: For immediate-vectors, the functions vsize-
1401: byte and vsize-word return the number of data
1402: elements, if one thinks of the binary data as
1403: being comprised of bytes or words.
1404:
1405:
1406:
1407: 2.4.3. vector modfication
1408:
1409: (vset 'v_vect 'x_index 'g_val)
1410: (vseti-byte 'V_vect 'x_bindex 'x_val)
1411: (vseti-word 'V_vect 'x_windex 'x_val)
1412: (vseti-long 'V_vect 'x_lindex 'x_val)
1413:
1414: RETURNS: the datum.
1415:
1416: SIDE EFFECT: The indexed element of the vector is set
1417: to the value. As noted above, for vseti-
1418: word and vseti-byte, the index is con-
1419: strued as the number of the data element
1420: within the vector. It is not a byte
1421: address. Also, for those two functions,
1422: the low order byte or word of x_val is
1423: what is stored.
1424:
1425: (vsetprop 'Vv_vect 'g_value)
1426:
1427: RETURNS: g_value. This should be either a symbol or a
1428: disembodied property list whose _c_a_r is a sym-
1429: bol identifying the type of the vector.
1430:
1431: SIDE EFFECT: the property list of Vv_vect is set to
1432: g_value.
1433:
1434: (vputprop 'Vv_vect 'g_value 'g_ind)
1435:
1436: RETURNS: g_value.
1437:
1438: SIDE EFFECT: If the vector property of Vv_vect is a
1439: disembodied property list, then vputprop
1440: adds the value g_value under the indicator
1441: g_ind. Otherwise, the old vector property
1442: is made the first element of the list.
1443:
1444:
1445:
1446:
1447: 9
1448:
1449: 9 Printed: August 5, 1983
1450:
1451:
1452:
1453:
1454:
1455:
1456:
1457: Data Structure Access 2-23
1458:
1459:
1460: 2.5. Arrays
1461:
1462: See Chapter 9 for a complete description of
1463: arrays. Some of these functions are part of a Maclisp
1464: array compatibility package, which represents only one
1465: simple way of using the array structure of FRANZ LISP.
1466:
1467:
1468:
1469: 2.5.1. array creation
1470:
1471: (marray 'g_data 's_access 'g_aux 'x_length 'x_delta)
1472:
1473: RETURNS: an array type with the fields set up from the
1474: above arguments in the obvious way (see
1475: 1.2.10).
1476:
1477: (*array 's_name 's_type 'x_dim1 ... 'x_dim_n)
1478: (array s_name s_type x_dim1 ... x_dim_n)
1479:
1480: WHERE: s_type may be one of t, nil, fixnum, flonum,
1481: fixnum-block and flonum-block.
1482:
1483: RETURNS: an array of type s_type with n dimensions of
1484: extents given by the x_dim_i.
1485:
1486: SIDE EFFECT: If s_name is non nil, the function defini-
1487: tion of s_name is set to the array struc-
1488: ture returned.
1489:
1490: NOTE: These functions create a Maclisp compatible
1491: array. In FRANZ LISP arrays of type t, nil, fix-
1492: num and flonum are equivalent and the elements of
1493: these arrays can be any type of lisp object.
1494: Fixnum-block and flonum-block arrays are res-
1495: tricted to fixnums and flonums respectively and
1496: are used mainly to communicate with foreign func-
1497: tions (see 8.5).
1498:
1499: NOTE: *_a_r_r_a_y evaluates its arguments, _a_r_r_a_y does not.
1500:
1501:
1502:
1503: 2.5.2. array predicate
1504:
1505:
1506:
1507:
1508:
1509:
1510:
1511:
1512: 9
1513:
1514: 9 Printed: August 5, 1983
1515:
1516:
1517:
1518:
1519:
1520:
1521:
1522: Data Structure Access 2-24
1523:
1524:
1525: (arrayp 'g_arg)
1526:
1527: RETURNS: t iff g_arg is of type array.
1528:
1529:
1530:
1531: 2.5.3. array accessors
1532:
1533:
1534: (getaccess 'a_array)
1535: (getaux 'a_array)
1536: (getdelta 'a_array)
1537: (getdata 'a_array)
1538: (getlength 'a_array)
1539:
1540: RETURNS: the field of the array object a_array given by
1541: the function name.
1542:
1543: (arrayref 'a_name 'x_ind)
1544:
1545: RETURNS: the x_ind_t_h element of the array object
1546: a_name. x_ind of zero accesses the first ele-
1547: ment.
1548:
1549: NOTE: _a_r_r_a_y_r_e_f uses the data, length and delta fields
1550: of a_name to determine which object to return.
1551:
1552: (arraycall s_type 'as_array 'x_ind1 ... )
1553:
1554: RETURNS: the element selected by the indicies from the
1555: array a_array of type s_type.
1556:
1557: NOTE: If as_array is a symbol then the function binding
1558: of this symbol should contain an array object.
1559: s_type is ignored by _a_r_r_a_y_c_a_l_l but is included
1560: for compatibility with Maclisp.
1561:
1562: (arraydims 's_name)
1563:
1564: RETURNS: a list of the type and bounds of the array
1565: s_name.
1566:
1567:
1568:
1569:
1570:
1571:
1572:
1573:
1574:
1575:
1576:
1577: 9
1578:
1579: 9 Printed: August 5, 1983
1580:
1581:
1582:
1583:
1584:
1585:
1586:
1587: Data Structure Access 2-25
1588:
1589:
1590: (listarray 'sa_array ['x_elements])
1591:
1592: RETURNS: a list of all of the elements in array
1593: sa_array. If x_elements is given, then only
1594: the first x_elements are returned.
1595:
1596:
1597:
1598: ____________________________________________________
1599:
1600: ; We will create a 3 by 4 array of general lisp objects
1601: -> (_a_r_r_a_y _e_r_n_i_e _t _3 _4)
1602: array[12]
1603:
1604: ; the array header is stored in the function definition slot of the
1605: ; symbol ernie
1606: -> (_a_r_r_a_y_p (_g_e_t_d '_e_r_n_i_e))
1607: t
1608: -> (_a_r_r_a_y_d_i_m_s (_g_e_t_d '_e_r_n_i_e))
1609: (t 3 4)
1610:
1611: ; store in ernie[2][2] the list (test list)
1612: -> (_s_t_o_r_e (_e_r_n_i_e _2 _2) '(_t_e_s_t _l_i_s_t))
1613: (test list)
1614:
1615: ; check to see if it is there
1616: -> (_e_r_n_i_e _2 _2)
1617: (test list)
1618:
1619: ; now use the low level function _a_r_r_a_y_r_e_f to find the same element
1620: ; arrays are 0 based and row-major (the last subscript varies the fastest)
1621: ; thus element [2][2] is the 10th element , (starting at 0).
1622: -> (_a_r_r_a_y_r_e_f (_g_e_t_d '_e_r_n_i_e) _1_0)
1623: (ptr to)(test list) ; the result is a value cell (thus the (ptr to))
1624: ____________________________________________________
1625:
1626:
1627:
1628:
1629:
1630:
1631: 2.5.4. array manipulation
1632:
1633:
1634:
1635:
1636:
1637:
1638:
1639:
1640:
1641:
1642: 9
1643:
1644: 9 Printed: August 5, 1983
1645:
1646:
1647:
1648:
1649:
1650:
1651:
1652: Data Structure Access 2-26
1653:
1654:
1655: (putaccess 'a_array 'su_func)
1656: (putaux 'a_array 'g_aux)
1657: (putdata 'a_array 'g_arg)
1658: (putdelta 'a_array 'x_delta)
1659: (putlength 'a_array 'x_length)
1660:
1661: RETURNS: the second argument to the function.
1662:
1663: SIDE EFFECT: The field of the array object given by the
1664: function name is replaced by the second
1665: argument to the function.
1666:
1667: (store 'l_arexp 'g_val)
1668:
1669: WHERE: l_arexp is an expression which references an
1670: array element.
1671:
1672: RETURNS: g_val
1673:
1674: SIDE EFFECT: the array location which contains the ele-
1675: ment which l_arexp references is changed
1676: to contain g_val.
1677:
1678: (fillarray 's_array 'l_itms)
1679:
1680: RETURNS: s_array
1681:
1682: SIDE EFFECT: the array s_array is filled with elements
1683: from l_itms. If there are not enough ele-
1684: ments in l_itms to fill the entire array,
1685: then the last element of l_itms is used to
1686: fill the remaining parts of the array.
1687:
1688:
1689:
1690: 2.6. Hunks
1691:
1692: Hunks are vector-like objects whose size can
1693: range from 1 to 128 elements. Internally hunks are
1694: allocated in sizes which are powers of 2. In order to
1695: create hunks of a given size, a hunk with at least
1696: that many elements is allocated and a distinguished
1697: symbol EMPTY is placed in those elements not
1698: requested. Most hunk functions respect those dis-
1699: tinguished symbols, but there are two (*_m_a_k_h_u_n_k and
1700: *_r_p_l_a_c_x) which will overwrite the distinguished sym-
1701: bol.
1702:
1703:
1704:
1705:
1706:
1707: 9
1708:
1709: 9 Printed: August 5, 1983
1710:
1711:
1712:
1713:
1714:
1715:
1716:
1717: Data Structure Access 2-27
1718:
1719:
1720: 2.6.1. hunk creation
1721:
1722: (hunk 'g_val1 ['g_val2 ... 'g_val_n])
1723:
1724: RETURNS: a hunk of length n whose elements are initial-
1725: ized to the g_val_i.
1726:
1727: NOTE: the maximum size of a hunk is 128.
1728:
1729: EXAMPLE: (_h_u_n_k _4 '_s_h_a_r_p '_k_e_y_s) = {4 sharp keys}
1730:
1731: (makhunk 'xl_arg)
1732:
1733: RETURNS: a hunk of length xl_arg initialized to all
1734: nils if xl_arg is a fixnum. If xl_arg is a
1735: list, then we return a hunk of size
1736: (_l_e_n_g_t_h '_x_l__a_r_g) initialized to the elements
1737: in xl_arg.
1738:
1739: NOTE: (_m_a_k_h_u_n_k '(_a _b _c)) is equivalent to
1740: (_h_u_n_k '_a '_b '_c).
1741:
1742: EXAMPLE: (_m_a_k_h_u_n_k _4) = {_n_i_l _n_i_l _n_i_l _n_i_l}
1743:
1744: (*makhunk 'x_arg)
1745:
1746: RETURNS: a hunk of size 2[x_arg] initialized to EMPTY.
1747:
1748: NOTE: This is only to be used by such functions as _h_u_n_k
1749: and _m_a_k_h_u_n_k which create and initialize hunks for
1750: users.
1751:
1752:
1753:
1754: 2.6.2. hunk accessor
1755:
1756: (cxr 'x_ind 'h_hunk)
1757:
1758: RETURNS: element x_ind (starting at 0) of hunk h_hunk.
1759:
1760: (hunk-to-list 'h_hunk)
1761:
1762: RETURNS: a list consisting of the elements of h_hunk.
1763:
1764:
1765:
1766: 2.6.3. hunk manipulators
1767:
1768:
1769:
1770:
1771:
1772: 9
1773:
1774: 9 Printed: August 5, 1983
1775:
1776:
1777:
1778:
1779:
1780:
1781:
1782: Data Structure Access 2-28
1783:
1784:
1785: (rplacx 'x_ind 'h_hunk 'g_val)
1786: (*rplacx 'x_ind 'h_hunk 'g_val)
1787:
1788: RETURNS: h_hunk
1789:
1790: SIDE EFFECT: Element x_ind (starting at 0) of h_hunk is
1791: set to g_val.
1792:
1793: NOTE: _r_p_l_a_c_x will not modify one of the distinguished
1794: (EMPTY) elements whereas *_r_p_l_a_c_x will.
1795:
1796: (hunksize 'h_arg)
1797:
1798: RETURNS: the size of the hunk h_arg.
1799:
1800: EXAMPLE: (_h_u_n_k_s_i_z_e (_h_u_n_k _1 _2 _3)) = 3
1801:
1802:
1803:
1804: 2.7. Bcds
1805:
1806: A bcd object contains a pointer to compiled code
1807: and to the type of function object the compiled code
1808: represents.
1809:
1810: (getdisc 'y_bcd)
1811: (getentry 'y_bcd)
1812:
1813: RETURNS: the field of the bcd object given by the func-
1814: tion name.
1815:
1816: (putdisc 'y_func 's_discipline)
1817:
1818: RETURNS: s_discipline
1819:
1820: SIDE EFFECT: Sets the discipline field of y_func to
1821: s_discipline.
1822:
1823:
1824:
1825: 2.8. Structures
1826:
1827: There are three common structures constructed out
1828: of list cells: the assoc list, the property list and
1829: the tconc list. The functions below manipulate these
1830: structures.
1831:
1832:
1833:
1834: 2.8.1. assoc list
1835:
1836: An `assoc list' (or alist) is a common lisp
1837: data structure. It has the form
1838:
1839:
1840: Printed: August 5, 1983
1841:
1842:
1843:
1844:
1845:
1846:
1847:
1848: Data Structure Access 2-29
1849:
1850:
1851: ((key1 . value1) (key2 . value2) (key3 . value3) ... (keyn . valuen))
1852:
1853: (assoc 'g_arg1 'l_arg2)
1854: (assq 'g_arg1 'l_arg2)
1855:
1856: RETURNS: the first top level element of l_arg2 whose
1857: _c_a_r is _e_q_u_a_l (with _a_s_s_o_c) or _e_q (with _a_s_s_q) to
1858: g_arg1.
1859:
1860: NOTE: Usually l_arg2 has an _a-_l_i_s_t structure and g_arg1
1861: acts as key.
1862:
1863: (sassoc 'g_arg1 'l_arg2 'sl_func)
1864:
1865: RETURNS: the result of
1866: (_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)))
1867:
1868: NOTE: sassoc is written as a macro.
1869:
1870: (sassq 'g_arg1 'l_arg2 'sl_func)
1871:
1872: RETURNS: the result of
1873: (_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)))
1874:
1875: NOTE: sassq is written as a macro.
1876:
1877:
1878:
1879: ____________________________________________________
1880:
1881: ; _a_s_s_o_c or _a_s_s_q is given a key and an assoc list and returns
1882: ; the key and value item if it exists, they differ only in how they test
1883: ; for equality of the keys.
1884:
1885: -> (_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)))
1886: ((alpha . a) ((complex key) . b) (junk . x))
1887:
1888: ; we should use _a_s_s_q when the key is an atom
1889: -> (_a_s_s_q '_a_l_p_h_a _a_l_i_s_t)
1890: (alpha . a)
1891:
1892: ; but it may not work when the key is a list
1893: -> (_a_s_s_q '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
1894: nil
1895:
1896: ; however _a_s_s_o_c will always work
1897: -> (_a_s_s_o_c '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
1898: ((complex key) . b)
1899: ____________________________________________________
1900:
1901:
1902:
1903: 9
1904:
1905: 9 Printed: August 5, 1983
1906:
1907:
1908:
1909:
1910:
1911:
1912:
1913: Data Structure Access 2-30
1914:
1915:
1916: (sublis 'l_alst 'l_exp)
1917:
1918: WHERE: l_alst is an _a-_l_i_s_t.
1919:
1920: RETURNS: the list l_exp with every occurrence of key_i
1921: replaced by val_i.
1922:
1923: NOTE: new list structure is returned to prevent modifi-
1924: cation of l_exp. When a substitution is made, a
1925: copy of the value to substitute in is not made.
1926:
1927:
1928:
1929: 2.8.2. property list
1930:
1931: A property list consists of an alternating
1932: sequence of keys and values. Normally a property
1933: list is stored on a symbol. A list is a 'disembo-
1934: died' property list if it contains an odd number of
1935: elements, the first of which is ignored.
1936:
1937: (plist 's_name)
1938:
1939: RETURNS: the property list of s_name.
1940:
1941: (setplist 's_atm 'l_plist)
1942:
1943: RETURNS: l_plist.
1944:
1945: SIDE EFFECT: the property list of s_atm is set to
1946: l_plist.
1947:
1948:
1949: (get 'ls_name 'g_ind)
1950:
1951: RETURNS: the value under indicator g_ind in ls_name's
1952: property list if ls_name is a symbol.
1953:
1954: NOTE: If there is no indicator g_ind in ls_name's pro-
1955: perty list nil is returned. If ls_name is a list
1956: of an odd number of elements then it is a disem-
1957: bodied property list. _g_e_t searches a disembodied
1958: property list by starting at its _c_d_r, and compar-
1959: ing every other element with g_ind, using _e_q.
1960:
1961:
1962:
1963:
1964:
1965:
1966:
1967:
1968: 9
1969:
1970: 9 Printed: August 5, 1983
1971:
1972:
1973:
1974:
1975:
1976:
1977:
1978: Data Structure Access 2-31
1979:
1980:
1981: (getl 'ls_name 'l_indicators)
1982:
1983: RETURNS: the property list ls_name beginning at the
1984: first indicator which is a member of the list
1985: l_indicators, or nil if none of the indicators
1986: in l_indicators are on ls_name's property
1987: list.
1988:
1989: NOTE: If ls_name is a list, then it is assumed to be a
1990: disembodied property list.
1991:
1992:
1993: (putprop 'ls_name 'g_val 'g_ind)
1994: (defprop ls_name g_val g_ind)
1995:
1996: RETURNS: g_val.
1997:
1998: SIDE EFFECT: Adds to the property list of ls_name the
1999: value g_val under the indicator g_ind.
2000:
2001: NOTE: _p_u_t_p_r_o_p evaluates it arguments, _d_e_f_p_r_o_p does not.
2002: ls_name may be a disembodied property list, see
2003: _g_e_t.
2004:
2005: (remprop 'ls_name 'g_ind)
2006:
2007: RETURNS: the portion of ls_name's property list begin-
2008: ning with the property under the indicator
2009: g_ind. If there is no g_ind indicator in
2010: ls_name's plist, nil is returned.
2011:
2012: SIDE EFFECT: the value under indicator g_ind and g_ind
2013: itself is removed from the property list
2014: of ls_name.
2015:
2016: NOTE: ls_name may be a disembodied property list, see
2017: _g_e_t.
2018:
2019:
2020:
2021:
2022:
2023:
2024:
2025:
2026:
2027:
2028:
2029:
2030:
2031:
2032:
2033: 9
2034:
2035: 9 Printed: August 5, 1983
2036:
2037:
2038:
2039:
2040:
2041:
2042:
2043: Data Structure Access 2-32
2044:
2045:
2046:
2047: ____________________________________________________
2048:
2049: -> (_p_u_t_p_r_o_p '_x_l_a_t_e '_a '_a_l_p_h_a)
2050: a
2051: -> (_p_u_t_p_r_o_p '_x_l_a_t_e '_b '_b_e_t_a)
2052: b
2053: -> (_p_l_i_s_t '_x_l_a_t_e)
2054: (alpha a beta b)
2055: -> (_g_e_t '_x_l_a_t_e '_a_l_p_h_a)
2056: a
2057: ; use of a disembodied property list:
2058: -> (_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)
2059: kls
2060: ____________________________________________________
2061:
2062:
2063:
2064:
2065:
2066:
2067: 2.8.3. tconc structure
2068:
2069: A tconc structure is a special type of list
2070: designed to make it easy to add objects to the end.
2071: It consists of a list cell whose _c_a_r points to a
2072: list of the elements added with _t_c_o_n_c or _l_c_o_n_c and
2073: whose _c_d_r points to the last list cell of the list
2074: pointed to by the _c_a_r.
2075:
2076: (tconc 'l_ptr 'g_x)
2077:
2078: WHERE: l_ptr is a tconc structure.
2079:
2080: RETURNS: l_ptr with g_x added to the end.
2081:
2082: (lconc 'l_ptr 'l_x)
2083:
2084: WHERE: l_ptr is a tconc structure.
2085:
2086: RETURNS: l_ptr with the list l_x spliced in at the end.
2087:
2088:
2089:
2090:
2091:
2092:
2093:
2094:
2095:
2096:
2097:
2098: 9
2099:
2100: 9 Printed: August 5, 1983
2101:
2102:
2103:
2104:
2105:
2106:
2107:
2108: Data Structure Access 2-33
2109:
2110:
2111:
2112: ____________________________________________________
2113:
2114: ; A _t_c_o_n_c structure can be initialized in two ways.
2115: ; nil can be given to _t_c_o_n_c in which case _t_c_o_n_c will generate
2116: ; a _t_c_o_n_c structure.
2117:
2118: ->(_s_e_t_q _f_o_o (_t_c_o_n_c _n_i_l _1))
2119: ((1) 1)
2120:
2121: ; Since _t_c_o_n_c destructively adds to
2122: ; the list, you can now add to foo without using _s_e_t_q again.
2123:
2124: ->(_t_c_o_n_c _f_o_o _2)
2125: ((1 2) 2)
2126: ->_f_o_o
2127: ((1 2) 2)
2128:
2129: ; Another way to create a null _t_c_o_n_c structure
2130: ; is to use (_n_c_o_n_s _n_i_l).
2131:
2132: ->(_s_e_t_q _f_o_o (_n_c_o_n_s _n_i_l))
2133: (nil)
2134: ->(_t_c_o_n_c _f_o_o _1)
2135: ((1) 1)
2136:
2137: ; now see what _l_c_o_n_c can do
2138: -> (_l_c_o_n_c _f_o_o _n_i_l)
2139: ((1) 1) ; no change
2140: -> (_l_c_o_n_c _f_o_o '(_2 _3 _4))
2141: ((1 2 3 4) 4)
2142: ____________________________________________________
2143:
2144:
2145:
2146:
2147:
2148:
2149: 2.8.4. fclosures
2150:
2151: An fclosure is a functional object which
2152: admits some data manipulations. They are discussed
2153: in 8.4. Internally, they are constructed from vec-
2154: tors.
2155:
2156:
2157:
2158:
2159:
2160:
2161:
2162:
2163: 9
2164:
2165: 9 Printed: August 5, 1983
2166:
2167:
2168:
2169:
2170:
2171:
2172:
2173: Data Structure Access 2-34
2174:
2175:
2176: (fclosure 'l_vars 'g_funobj)
2177:
2178: WHERE: l_vars is a list of variables, g_funobj is any
2179: object that can be funcalled (including, fclo-
2180: sures).
2181:
2182: RETURNS: A vector which is the fclosure.
2183:
2184: (fclosure-alist 'v_fclosure)
2185:
2186: RETURNS: An association list representing the variables
2187: in the fclosure. This is a snapshot of the
2188: current state of the fclosure. If the bind-
2189: ings in the fclosure are changed, any previ-
2190: ously calculated results of _f_c_l_o_s_u_r_e-_a_l_i_s_t
2191: will not change.
2192:
2193: (fclosure-function 'v_fclosure)
2194:
2195: RETURNS: the functional object part of the fclosure.
2196:
2197: (fclosurep 'v_fclosure)
2198:
2199: RETURNS: t iff the argument is an fclosure.
2200:
2201: (symeval-in-fclosure 'v_fclosure 's_symbol)
2202:
2203: RETURNS: the current binding of a particular symbol in
2204: an fclosure.
2205:
2206: (set-in-fclosure 'v_fclosure 's_symbol 'g_newvalue)
2207:
2208: RETURNS: g_newvalue.
2209:
2210: SIDE EFFECT: The variable s_symbol is bound in the
2211: fclosure to g_newvalue.
2212:
2213:
2214:
2215: 2.9. Random functions
2216:
2217: The following functions don't fall into any of
2218: the classifications above.
2219:
2220:
2221:
2222:
2223:
2224:
2225:
2226:
2227:
2228: 9
2229:
2230: 9 Printed: August 5, 1983
2231:
2232:
2233:
2234:
2235:
2236:
2237:
2238: Data Structure Access 2-35
2239:
2240:
2241: (bcdad 's_funcname)
2242:
2243: RETURNS: a fixnum which is the address in memory where
2244: the function s_funcname begins. If s_funcname
2245: is not a machine coded function (binary) then
2246: _b_c_d_a_d returns nil.
2247:
2248: (copy 'g_arg)
2249:
2250: RETURNS: A structure _e_q_u_a_l to g_arg but with new list
2251: cells.
2252:
2253: (copyint* 'x_arg)
2254:
2255: RETURNS: a fixnum with the same value as x_arg but in a
2256: freshly allocated cell.
2257:
2258: (cpy1 'xvt_arg)
2259:
2260: RETURNS: a new cell of the same type as xvt_arg with
2261: the same value as xvt_arg.
2262:
2263: (getaddress 's_entry1 's_binder1 'st_discipline1 [... ...
2264: ...])
2265:
2266: RETURNS: the binary object which s_binder1's function
2267: field is set to.
2268:
2269: NOTE: This looks in the running lisp's symbol table for
2270: a symbol with the same name as s_entry_i. It then
2271: creates a binary object whose entry field points
2272: to s_entry_i and whose discipline is
2273: st_discipline_i. This binary object is stored in
2274: the function field of s_binder_i. If
2275: st_discipline_i is nil, then "subroutine" is used
2276: by default. This is especially useful for _c_f_a_s_l
2277: users.
2278:
2279: (macroexpand 'g_form)
2280:
2281: RETURNS: g_form after all macros in it are expanded.
2282:
2283: NOTE: This function will only macroexpand expressions
2284: which could be evaluated and it does not know
2285: about the special nlambdas such as _c_o_n_d and _d_o,
2286: thus it misses many macro expansions.
2287:
2288:
2289:
2290:
2291:
2292:
2293: 9
2294:
2295: 9 Printed: August 5, 1983
2296:
2297:
2298:
2299:
2300:
2301:
2302:
2303: Data Structure Access 2-36
2304:
2305:
2306: (ptr 'g_arg)
2307:
2308: RETURNS: a value cell initialized to point to g_arg.
2309:
2310: (quote g_arg)
2311:
2312: RETURNS: g_arg.
2313:
2314: NOTE: the reader allows you to abbreviate (quote foo)
2315: as 'foo.
2316:
2317: (kwote 'g_arg)
2318:
2319: RETURNS: (_l_i_s_t (_q_u_o_t_e _q_u_o_t_e) _g__a_r_g).
2320:
2321: (replace 'g_arg1 'g_arg2)
2322:
2323: WHERE: g_arg1 and g_arg2 must be the same type of
2324: lispval and not symbols or hunks.
2325:
2326: RETURNS: g_arg2.
2327:
2328: SIDE EFFECT: The effect of _r_e_p_l_a_c_e is dependent on the
2329: type of the g_arg_i although one will
2330: notice a similarity in the effects. To
2331: understand what _r_e_p_l_a_c_e does to fixnum and
2332: flonum arguments, you must first under-
2333: stand that such numbers are `boxed' in
2334: FRANZ LISP. What this means is that if
2335: the symbol x has a value 32412, then in
2336: memory the value element of x's symbol
2337: structure contains the address of another
2338: word of memory (called a box) with 32412
2339: in it.
2340:
2341: Thus, there are two ways of changing the
2342: value of x: the first is to change the
2343: value element of x's symbol structure to
2344: point to a word of memory with a different
2345: value. The second way is to change the
2346: value in the box which x points to. The
2347: former method is used almost all of the
2348: time, the latter is used very rarely and
2349: has the potential to cause great confu-
2350: sion. The function _r_e_p_l_a_c_e allows you to
2351: do the latter, i.e., to actually change
2352: the value in the box.
2353:
2354: You should watch out for these situations.
2355: If you do (_s_e_t_q _y _x), then both x and y
2356: will point to the same box. If you now
2357: (_r_e_p_l_a_c_e _x _1_2_3_4_5), then y will also have
2358: the value 12345. And, in fact, there may
2359:
2360:
2361: Printed: August 5, 1983
2362:
2363:
2364:
2365:
2366:
2367:
2368:
2369: Data Structure Access 2-37
2370:
2371:
2372: be many other pointers to that box.
2373:
2374: Another problem with replacing fixnums is
2375: that some boxes are read-only. The fix-
2376: nums between -1024 and 1023 are stored in
2377: a read-only area and attempts to replace
2378: them will result in an "Illegal memory
2379: reference" error (see the description of
2380: _c_o_p_y_i_n_t* for a way around this problem).
2381:
2382: For the other valid types, the effect of
2383: _r_e_p_l_a_c_e is easy to understand. The fields
2384: of g_val1's structure are made eq to the
2385: corresponding fields of g_val2's struc-
2386: ture. For example, if x and y have
2387: lists as values then the effect of
2388: (_r_e_p_l_a_c_e _x _y) is the same as
2389: (_r_p_l_a_c_a _x (_c_a_r _y)) and (_r_p_l_a_c_d _x (_c_d_r _y)).
2390:
2391: (scons 'x_arg 'bs_rest)
2392:
2393: WHERE: bs_rest is a bignum or nil.
2394:
2395: RETURNS: a bignum whose first bigit is x_arg and whose
2396: higher order bigits are bs_rest.
2397:
2398: (setf g_refexpr 'g_value)
2399:
2400: NOTE: _s_e_t_f is a generalization of setq. Information
2401: may be stored by binding variables, replacing
2402: entries of arrays, and vectors, or being put on
2403: property lists, among others. Setf will allow
2404: the user to store data into some location, by
2405: mentioning the operation used to refer to the
2406: location. Thus, the first argument may be par-
2407: tially evaluated, but only to the extent needed
2408: to calculate a reference. _s_e_t_f returns g_value.
2409:
2410:
2411: ____________________________________________________
2412:
2413: (setf x 3) = (setq x 3)
2414: (setf (car x) 3) = (rplaca x 3)
2415: (setf (get foo 'bar) 3) = (putprop foo 3 'bar)
2416: (setf (vref vector index) value) = (vset vector index value)
2417: ____________________________________________________
2418:
2419:
2420:
2421:
2422:
2423:
2424: 9
2425:
2426: 9 Printed: August 5, 1983
2427:
2428:
2429:
2430:
2431:
2432:
2433:
2434: Data Structure Access 2-38
2435:
2436:
2437: (sort 'l_data 'u_comparefn)
2438:
2439: RETURNS: a list of the elements of l_data ordered by
2440: the comparison function u_comparefn
2441:
2442: SIDE EFFECT: the list l_data is modified rather than
2443: allocate new storage.
2444:
2445: NOTE: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) should return something
2446: non-nil if g-x can precede g_y in sorted order;
2447: nil if g_y must precede g_x. If u_comparefn is
2448: nil, alphabetical order will be used.
2449:
2450: (sortcar 'l_list 'u_comparefn)
2451:
2452: RETURNS: a list of the elements of l_list with the
2453: _c_a_r's ordered by the sort function
2454: u_comparefn.
2455:
2456: SIDE EFFECT: the list l_list is modified rather than
2457: allocating new storage.
2458:
2459: NOTE: Like _s_o_r_t, if u_comparefn is nil, alphabetical
2460: order will be used.
2461:
2462:
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: 9
2490:
2491: 9 Printed: August 5, 1983
2492:
2493:
2494:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.