From: Michael R. Blair Date: Sun, 4 Apr 1993 20:48:36 +0000 (+0000) Subject: Added document strings for primitives. X-Git-Tag: 20090517-FFI~8391 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=59ae207ffd6beb7afd588be7249fba9e10a04d78;p=mit-scheme.git Added document strings for primitives. --- diff --git a/v7/src/microcode/list.c b/v7/src/microcode/list.c index ec115f807..890a648c4 100644 --- a/v7/src/microcode/list.c +++ b/v7/src/microcode/list.c @@ -1,6 +1,6 @@ /* -*-C-*- -$Id: list.c,v 9.30 1993/02/10 23:53:26 adams Exp $ +$Id: list.c,v 9.31 1993/04/04 20:48:36 ziggy Exp $ Copyright (c) 1987-92 Massachusetts Institute of Technology @@ -37,7 +37,10 @@ MIT in each case. */ #include "scheme.h" #include "prims.h" -DEFINE_PRIMITIVE ("PAIR?", Prim_pair, 1, 1, 0) +DEFINE_PRIMITIVE ("PAIR?", Prim_pair, 1, 1, + "(object)\n\ + Returns #t if object is a pair; otherwise returns #f.\ +") { fast SCHEME_OBJECT object; PRIMITIVE_HEADER (1); @@ -56,27 +59,44 @@ DEFUN (cons, (car, cdr), return (MAKE_POINTER_OBJECT (TC_LIST, (Free - 2))); } -DEFINE_PRIMITIVE ("CONS", Prim_cons, 2, 2, 0) +DEFINE_PRIMITIVE ("CONS", Prim_cons, 2, 2, + "(obj1 obj2)\n\ + Returns a newly allocated pair whose car is OBJ1 and whose cdr is OBJ2.\n\ + The pair is guaranteed to be different (in the sense of EQV?) from other\n\ + previously existing object.\ + ") { PRIMITIVE_HEADER (2); PRIMITIVE_RETURN (cons ((ARG_REF (1)), (ARG_REF (2)))); } -DEFINE_PRIMITIVE ("CAR", Prim_car, 1, 1, 0) +DEFINE_PRIMITIVE ("CAR", Prim_car, 1, 1, + "(pair)\n\ + Returns the contents of the car field of PAIR.\n\ + Note that it is an error to take the CAR of an empty list.\ + ") { PRIMITIVE_HEADER (1); CHECK_ARG (1, PAIR_P); PRIMITIVE_RETURN (PAIR_CAR (ARG_REF (1))); } -DEFINE_PRIMITIVE ("CDR", Prim_cdr, 1, 1, 0) +DEFINE_PRIMITIVE ("CDR", Prim_cdr, 1, 1, + "(pair)\n\ + Returns the contents of the cdr field of PAIR.\n\ + Note that it is an error to take the CDR of an empty list.\ + ") { PRIMITIVE_HEADER (1); CHECK_ARG (1, PAIR_P); PRIMITIVE_RETURN (PAIR_CDR (ARG_REF (1))); } -DEFINE_PRIMITIVE ("SET-CAR!", Prim_set_car, 2, 2, 0) +DEFINE_PRIMITIVE ("SET-CAR!", Prim_set_car, 2, 2, + "(pair object)\n\ + Store OBJECT in the car field of PAIR.\n\ + The value returned by SET-CAR! is unspecified.\ + ") { PRIMITIVE_HEADER (2); CHECK_ARG (1, PAIR_P); @@ -89,7 +109,11 @@ DEFINE_PRIMITIVE ("SET-CAR!", Prim_set_car, 2, 2, 0) PRIMITIVE_RETURN (UNSPECIFIC); } -DEFINE_PRIMITIVE ("SET-CDR!", Prim_set_cdr, 2, 2, 0) +DEFINE_PRIMITIVE ("SET-CDR!", Prim_set_cdr, 2, 2, + "(pair object)\n\ + Store OBJECT in the cdr field of PAIR.\n\ + The value returned by SET-CDR! is unspecified.\ + ") { PRIMITIVE_HEADER (2); CHECK_ARG (1, PAIR_P); @@ -110,7 +134,36 @@ DEFINE_PRIMITIVE ("SET-CDR!", Prim_set_cdr, 2, 2, 0) 11 = CAR 111 = CAAR 100 = CDDR ... */ -DEFINE_PRIMITIVE ("GENERAL-CAR-CDR", Prim_general_car_cdr, 2, 2, 0) +DEFINE_PRIMITIVE ("GENERAL-CAR-CDR", Prim_general_car_cdr, 2, 2, + "(object path)\n\ + This procedure is a generalization of `car' and `cdr'. PATH\n\ + encodes a particular sequence of `car' and `cdr' operations, which\n\ + `general-car-cdr' executes on OBJECT. PATH is an exact\n\ + non-negative integer that encodes the operations in a bitwise\n\ + fashion: a zero bit represents a `cdr' operation, and a one bit\n\ + represents a `car'. The bits are executed LSB to MSB, and the\n\ + most significant one bit, rather than being interpreted as an\n\ + operation, signals the end of the sequence.\n\ + \n\ + For example, the following are equivalent:\n\ + (general-car-cdr OBJECT #b1011)\n\ + (cdr (car (car OBJECT)))\n\ + \n\ + Here is a partial table of path/operation equivalents:\n\ + \n\ + #b10 cdr\n\ + #b11 car\n\ + #b100 cddr\n\ + #b101 cdar\n\ + #b110 cadr\n\ + #b111 caar\n\ + #b1000 cdddr\n\ + \n\ + Note that PATH is restricted to a machine-dependent range,\n\ + usually the size of a machine word. On many machines, this means that\n\ + the maximum length of PATH will be 30 operations (32 bits, less the\n\ + sign bit and the "end-of-sequence" bit).\ + ") { PRIMITIVE_HEADER (2); { @@ -131,7 +184,10 @@ DEFINE_PRIMITIVE ("GENERAL-CAR-CDR", Prim_general_car_cdr, 2, 2, 0) } } -DEFINE_PRIMITIVE ("LENGTH", Prim_length, 1, 1, 0) +DEFINE_PRIMITIVE ("LENGTH", Prim_length, 1, 1, + "(list)\n\ + Returns the length of LIST.\ + ") { fast SCHEME_OBJECT list; fast long i = 0; @@ -148,7 +204,27 @@ DEFINE_PRIMITIVE ("LENGTH", Prim_length, 1, 1, 0) PRIMITIVE_RETURN (LONG_TO_UNSIGNED_FIXNUM (i)); } -DEFINE_PRIMITIVE ("MEMQ", Prim_memq, 2, 2, 0) +DEFINE_PRIMITIVE ("MEMQ", Prim_memq, 2, 2, + "(object list)\n\ + Returns the first pair of LIST whose car is OBJECT;\n\ + the returned pair is always one from which LIST is composed.\n\ + If OBJECT does not occur in LIST, `#f' (n.b.: not the\n\ + empty list) is returned. `memq' uses `eq?' to compare OBJECT with\n\ + the elements of LIST, while `memv' uses `eqv?' and `member' uses\n\ + `equal?'.\n\ + \n\ + (memq 'a '(a b c)) => (a b c)\n\ + (memq 'b '(a b c)) => (b c)\n\ + (memq 'a '(b c d)) => #f\n\ + (memq (list 'a) '(b (a) c)) => #f\n\ + (member (list 'a) '(b (a) c)) => ((a) c)\n\ + (memq 101 '(100 101 102)) => unspecified\n\ + (memv 101 '(100 101 102)) => (101 102)\n\ + \n\ + Although they are often used as predicates, `memq', `memv', and\n\ + `member' do not have question marks in their names because they return\n\ + useful values rather than just `#t' or `#f'.\ + ") { fast SCHEME_OBJECT key; fast SCHEME_OBJECT list; @@ -168,7 +244,29 @@ DEFINE_PRIMITIVE ("MEMQ", Prim_memq, 2, 2, 0) PRIMITIVE_RETURN (SHARP_F); } -DEFINE_PRIMITIVE ("ASSQ", Prim_assq, 2, 2, 0) +DEFINE_PRIMITIVE ("ASSQ", Prim_assq, 2, 2, + "(object alist)\n\ + These procedures find the first pair in ALIST whose car field is\n\ + OBJECT, and return that pair; the returned pair is always an\n\ + *element* of ALIST, *not* one of the pairs from which ALIST is\n\ + composed. If no pair in ALIST has OBJECT as its car, `#f' (n.b.:\n\ + not the empty list) is returned. `assq' uses `eq?' to compare\n\ + OBJECT with the car fields of the pairs in ALIST, while `assv'\n\ + uses `eqv?' and `assoc' uses `equal?'.\n\ + \n\ + (define e '((a 1) (b 2) (c 3)))\n\ + (assq 'a e) => (a 1)\n\ + (assq 'b e) => (b 2)\n\ + (assq 'd e) => #f\n\ + (assq (list 'a) '(((a)) ((b)) ((c)))) => #f\n\ + (assoc (list 'a) '(((a)) ((b)) ((c)))) => ((a))\n\ + (assq 5 '((2 3) (5 7) (11 13))) => unspecified\n\ + (assv 5 '((2 3) (5 7) (11 13))) => (5 7)\n\ + \n\ + Although they are often used as predicates, `assq', `assv', and\n\ + `assoc' do not have question marks in their names because they return\n\ + useful values rather than just `#t' or `#f'.\ + ") { fast SCHEME_OBJECT key; fast SCHEME_OBJECT alist;