.c	Thursday  Dec 8,1983  22:16  NM+4D.7H.11M.50S.  -*- Bolio -*-

.chapter "Predicates"

.section "Type Predicates"

.subsection "Type Specifiers"

A term_i{type specifier} is an expression which may be used to
express a data-type constraint.
.table 3 250 250
.item nil
No object is of the type 3nil*;  3nil* is a subtype of all
types.
.item t
All objects are of the type 3t*.  For instance,
.lisp
(make-array '(10 10) :element-type t)
.end_lisp
makes an 10x10 array which can hold objects of any type.
.item 2type-name*
This is the most common form of type specifier;  just a type name, for
instance 3number*, 3double-float*, 3string*.
2type-name* may be the name of a flavor defined with
3defflavor* ((defflavor-fun)), by 3defstruct* in the absence
of directives telling it how to implement the structure
((defstruct-page)), or one of the many lan{nil} types noted in
various places in this document.
.item (not 2type-specifier*)
All objects which are 2not* of type 2type-specifier*.
.item (and 2ts1* 2ts2* ... 2tsn*)
The intersection of the types corresponding to the given type
specifiers.
.item (or 2ts1* 2ts1* ... 2tsn*)
The union of the types corresponding to the given type specifiers.
.item (member 2x1* 2x2* ... 2xn*)
This describes a type which is one of the objects 2x1*, 2x2*,
... 2xn*.  Equality is defined by 3eql* ((eql-fun)).
.item (satisfies 2function-name*)
An object is a "member" of this type if 2function-name* returns a
non-null value when applied to it, otherwise it is not.
.end_table
There are some more complex forms which are used variously as synonyms
for, and constraints on, more general types.  For instance:
.table 3 250 250
.item (integer 2low* 2high*)
An object is of this type if it is an integer between 2low* and
2high*.  2low* and 2high* may be integers, in which case
the boundary check is 2inclusive*, lists of integers, in which
case the boundary check is 2exclusive*, or the atom 3**, which
signifies infinity of the appropriate sign.  Thus, 3(integer 0 *)*
is a type specifier for all non-negative integers, and 3(integer (0)
*)* or 3(integer 1 *)* for all positive integers.
.item (signed-byte 2size*)
.item1 (unsigned-byte 2size*)
An object is of these types if it can be represented in the
appropriate form in twos-complement notation in a field of the
specified size.  (Without a hidden-bit convention.)  Thus,
3(signed-byte 3)* is the same as 3(integer -4 3)*, and
3(unsigned-byte 3)* is the same as 3(integer 0 7)*.
.item bit
Either 30* or 31*.
.item (array 2element-type* 2dimensions*)
Hairier.  Probably not worthwhile using yet.
.end_table


.subsection "General Type Predicates"

.defun typep object &optional type-specifier
If only one argument is supplied, this is (somewhat) like
lan{maclisp} typep, and returns the exact implementation type of
2object*.  In lan{nil}, this is usually something too specific
to be worth looking at.

Otherwise, returns (true) if 2object* is of type
2type-specifier*, (false) otherwise.  See the description of
type specifiers, above.
.end_defun

.defun subtypep type-specifier-1 type-specifier-2
3subtypep* attempts to determine if 2type-specifier-1* is a
subtype of 2type-specifier-2*.  It returns two values;  the
2second* will be 3t* if the relation could be determined,
3nil* if it could not be.  The first is 3t* if the
relation can be determined and 2type-specifier-1* is in fact a
subtype of 2type-specifier-2*, 3nil* otherwise.

In lan{nil}, if the type specifiers are atomic type names and
2type-specifier-1* is a subtype of 2type-specifier-2*, then
3subtypep* will probably succeed in determining this.  If
2type-specifier-1* is 2not* a subtype of
2type-specifier-2*, then 3subtypep* may fail to be able to
determine the relation, because it may not know that particular
supertypes are mutually exclusive.

For instance,
.lisp
(subtypep 'fixnum 'number)	=>  {t, t}
(subtypep 'character 'number)	=>  {nil, t}
(subtypep 'number 'fixnum)	=>  {nil, t}
(subtypep '(satisfies fixnump) 'number)	 =>  {nil, nil}
.end_lisp
.end_defun

.subsection "Specific Type Predicates"

.defun null object
This returns 3t* if 2object* is 3nil*, 3nil*
otherwise.  Stylistically, 3null* is used to test for 2object*
being the empty list, whereas 3not* ((not-fun)), which is
functionally equivalent because of the empty-list/boolean-false
duality of 3nil*, is used to test for boolean falseness.  This is
why constructs of the form
.lisp
(if (not (null x)) 2frob-non-null-x* 2frob-null-x*)
.end_lisp
are so prevalent.
.end_defun

.defun symbolp object
Returns 3t* if 2object* is a symbol, 3nil* otherwise.
.end_defun

.defun consp object
Returns 3t* if 2object* is a 3cons*, 3nil* otherwise.
This is the same as 3(not (atom 2object*))*.
.end_defun

.defun listp object
3consp* or 3null*.
.end_defun

.defun fixnump object
.defun1 characterp object
These test for the exact types 3fixnum* and 3character*.
.end_defun

.defun string-char-p character
Tells if 2character* is a character which may be stored in a
string.  This will be a type of sorts in lan{common lisp}, such that
a string is a vector with elements of type 3string-char*.  Note
that 3string-char-p* requires its argument to be a
character, as opposed to just any object;  it is not really a general
type predicate.

In lan{nil}, this is characters with 2bits* and 2font* of
30* (see chapter (character-chapter-number)).
.end_defun

.defun stringp object
.defun1 vectorp object
Tell if 2object* is a string or vector respectively.  These are
equivalent to doing 3(typep 2object* 'string)* and 3(typep
2object* 'vector)*.
.end_defun

.defun numberp object
.defun1 floatp object
These are the same as 3(typep 2object* 'number)* and 3(typep
2object* 'float)* respectively.
.end_defun

.defun closurep object
Tells if 2object* is a closure.
.end_defun

The following are supported for lan{maclisp} compatibility:

.defun pairp object
This is synonymous with 3consp*.  Once upon a time, the name for
3cons* in lan{nil} was 3pair*, and the function 3pairp*
was installed in lan{maclisp}.  Now, lan{nil} and lan{common
lisp} call a cons a 3cons*.
.end_defun

.defun bigp object
.lisp
(typep 2object* 'bignum)
.end_lisp
.end_defun

.defun fixp object
Equivalent to 3integerp*, i.e., 3(typep 2object*
'integer)*.  This name should be avoided because of possible
confusion with 3fixnump*.
.end_defun

.defun flonump object
This is the same as 3(typep 2object* 'double-float)*, for
historical reasons, 2not* the same as 3floatp*.  It is
provided for lan{maclisp} compatibility only.
.end_defun


.section "Equality Predicates"
.cindex equality

Note also 3null* ((null-fun)) and 3not* ((not-fun)), for
testing for 3nil*.

.defun eq x y
'cindex identity of objects
'cindex object equality
This tells if 2x* and 2y* are the exact same object.
Implementationally, this is true if 2x* and 2y* are the same
"pointer".  For instance,
.lisp
(setq *foo* (cons 'a 'b))	=>  (a . b)
(eq *foo* *foo*)		=>  t
(setq *bar* (cons 'a 'b))	=>  (a . b)
(eq *foo* *bar*)		=>  nil
.end_lisp
Philosophically, what this predicate says is that if one can
side-effect the object 2x*, then the equivalent side-effect will
happen to 2y* simultaneously;  in other words, they are
functionally indistinguishable.  There are certain kinds of objects
which have absolutely no internal structure, and thus cannot be
side-effected.
These
objects have the behaviour that two of them created the same will then
be 3eq*.  As a rule, for code transportability, resilience, and
clarity, this behaviour is something which should not be depended on.
In lan{nil}, it happens that objects of type 3fixnum* and
3character*, among some other more obscure ones, exhibit this
behaviour;  this may not be true in other lan{lisp} implementations,
however (it is not in lan{maclisp}, for instance).  For comparisons
of such objects, 3eq* is not the proper test;  3eql* is.
.end_defun

.defun eql x y
'cindex behavioural equality
3eql* is a predicate for testing for equality on non-structured
objects.  It is true if 2x* and 2y* are both numbers of the
same type and numerically equal, or if 2x* and 2y* are
both objects of type 3character* and represent the same character,
or (otherwise) if they are the same object (3eq*).  This is the
default predicate for many functions such as 3member* and
3subst*, and also for the 3case* special form ((case-fun)).
.end_defun

.defun equal x y
'cindex value equality
Fairly standard 3equal*.  Numbers, characters, symbols, and most
random types are compared as by 3eql*.  Conses are 3equal* if
their 3car*s and 3cdr*s are 3equal*.  Arrays are
considered 3equal* only if they are 3eq*, with the following
exceptions:
.table 2 250 250 0 0 0
.item (1)
Two strings are 3equal* if they have the same length and their
corresponding characters are 3equal*.  Note that they therefore
will not be 3equal* if any of those characters differ in case,
making this incompatible with lan{lispm} usage.
.item (2)
Two bit vectors are 3equal* if they have the same length, and the
same elements.
.item (3)
In lan{nil}, and in lan{nil} only (not lan{common lisp}), two
general vectors are 3equal* if they have the same length and
3equal* components.  The lengths are determined as by 3length*,
that is, the fill pointer of a vector is used if it has one.  This
exception to the lan{common lisp} definition is to compensate for
an earlier definition of 3equal* which compared arrays by
comparing their elements if they had the same rank, dimensions, and
element-types, and should not be depended upon.
.end_table

3equal* is implemented recursively, so may fail to terminate (or
blow out with stack overflow) on circular structures.
.end_defun

.defun equalp x y
This is a more "general" version of 3equal*.  Numbers are
considered to be 3equalp* if they are numerically equal;  type
conversion will occur if needed to perform the comparison (see
3=*, (=-fun)).  Characters are compared with 3char-equal*
((char-equal-fun)), so are considered 3equalp* even if they
differ in case.  Conses are 3equalp* if their respective
3car*s and 3cdr*s are 3equalp*.  Arrays are 3equalp*
if they have the same rank and dimensions, and if their corresponding
elements are 3equalp*:  thus, a string will be 3equalp* to a
general vector containing 3equalp* characters:
.lisp
(equalp #(#\F #\o #\o) "foO")  =>  t
.end_lisp

3equalp*, like 3equal*, is implemented recursively so may die
on circular structures.
.end_defun

