/* -*-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
#include "scheme.h"
#include "prims.h"
\f
-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);
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);
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);
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);
{
}
}
-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;
PRIMITIVE_RETURN (LONG_TO_UNSIGNED_FIXNUM (i));
}
\f
-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;
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;
projects / mit-scheme.git / commitdiff