% -*- Mode: TeX -*- %%% ========== NIL \begincom{nil}\ftype{Type} \label Supertypes:: all \term{types} \label Description:: \Thetype{nil} contains no \term{objects} and so is also called the \term{empty type}. %% 2.15.0 5 \Thetype{nil} is a \term{subtype} of every \term{type}. No \term{object} is \oftype{nil}. \label Notes:: The \term{type} containing the \term{object} \nil\ is \thetype{null}, not \thetype{nil}. \endcom%{nil}\ftype{Type} %%% ========== BOOLEAN \begincom{boolean}\ftype{Type} \label Supertypes:: \typeref{boolean}, \typeref{symbol}, \typeref{t} \label Description:: \Thetype{boolean} contains the \term{symbols} \misc{t} and \misc{nil}, which represent true and false, respectively. \label See Also:: \misc{t} (\term{constant variable}), \misc{nil} (\term{constant variable}), \specref{if}, \funref{not}, \funref{complement} \label Notes:: Conditional operations, such as \specref{if}, permit the use of \term{generalized booleans}, not just \term{booleans}; any \term{non-nil} value, not just \misc{t}, counts as true for a \term{generalized boolean}. However, as a matter of convention, the \term{symbol} \misc{t} is considered the canonical value to use even for a \term{generalized boolean} when no better choice presents itself. \endcom%{boolean}\ftype{Type} %Number and its subtypes moved to dict-numbers. %Character and its subtypes moved to dict-characters. %System Class SYMBOL moved to dict-symbols. %Type KEYWORD moved to dict-symbols. %Type SEQUENCE moved to dict-sequence. %Type LIST, NULL, CONS, ATOM, ... moved to dict-conses. %Types ARRAY, STRING, etc. to dict-strings. %% new definition here? %%% ========== FUNCTION \begincom{function}\ftype{System Class} \issue{FUNCTION-TYPE:X3J13-MARCH-88} \label Class Precedence List:: \typeref{function}, \typeref{t} \label Description:: A \term{function} is an \term{object} that represents code to be executed when an appropriate number of arguments is supplied. %Removed per symbolics comments: % A \term{function} can be supplied as an %argument without error to \funref{funcall} or \funref{apply}. A \term{function} is produced by \thespecform{function}, \thefunction{coerce}, \issue{SYNTACTIC-ENVIRONMENT-ACCESS:RETRACTED-MAR91} %the \thefunction{enclose}, \endissue{SYNTACTIC-ENVIRONMENT-ACCESS:RETRACTED-MAR91} or \thefunction{compile}. A \term{function} can be directly invoked by using it as the first argument to \funref{funcall}, \funref{apply}, or \specref{multiple-value-call}. %!!! Barrett says this syntax is confused. % Issues: &allow-other-keys, &key in value-typespec, &key mis-formatted where it already is. \label Compound Type Specifier Kind:: Specializing. \label Compound Type Specifier Syntax:: %% 4.5.0 12 \Deftype{function}{\ttbrac{arg-typespec \brac{value-typespec}}} \auxbnf{arg-typespec}{\lparen\starparam{typespec} \CR \ \ttbrac{{\opt} \starparam{typespec}} \CR \ \ttbrac{{\rest} \param{typespec}} \CR \ \ttbrac{{\key} \starparen{keyword typespec}}\rparen} \label Compound Type Specifier Arguments:: \param{typespec}---a \term{type specifier}. \param{value-typespec}---a \term{type specifier}. \label Compound Type Specifier Description:: \editornote{KMP: Isn't there some context info about ftype declarations to be merged here?} \editornote{KMP: This could still use some cleaning up.}%!!! \editornote{Sandra: Still need clarification about what happens if the number of arguments doesn't match the FUNCTION type declaration.} The list form of the \typeref{function} \term{type-specifier} can be used only for declaration and not for discrimination. Every element of this \term{type} is % I think the ``at least'' is confusing. --sjl 7 Mar 92 % a \term{function} that accepts arguments at least of the a \term{function} that accepts arguments of the types specified by the \param{argj-types} and returns values that are members of the \term{types} specified by \param{value-type}. The \keyref{optional}, \keyref{rest}, \keyref{key}, \issue{FUNCTION-TYPE-KEY-NAME:SPECIFY-KEYWORD} and \keyref{allow-other-keys} \endissue{FUNCTION-TYPE-KEY-NAME:SPECIFY-KEYWORD} markers can appear in the list of argument types. \issue{FUNCTION-TYPE-REST-LIST-ELEMENT:USE-ACTUAL-ARGUMENT-TYPE} The \term{type specifier} provided with \keyref{rest} is the \term{type} of each actual argument, not the \term{type} of the corresponding variable. \endissue{FUNCTION-TYPE-REST-LIST-ELEMENT:USE-ACTUAL-ARGUMENT-TYPE} \issue{FUNCTION-TYPE-KEY-NAME:SPECIFY-KEYWORD} The \keyref{key} parameters should be supplied as lists of the form {\tt (\param{keyword} \param{type})}. The \param{keyword} must be a valid keyword-name symbol as must be supplied in the actual arguments of a call. \issue{KEYWORD-ARGUMENT-NAME-PACKAGE:ANY} This is usually a \term{symbol} in \thepackage{keyword} but can be any \term{symbol}. \endissue{KEYWORD-ARGUMENT-NAME-PACKAGE:ANY} % tweaked to be less wordy --sjl 7 Mar 92 %The \keyref{allow-other-keys} declarations are interpreted as follows: %when \keyref{key} is given in a %\declref{function} \term{type specifier} \term{lambda list}, %it is safe to assume that the \term{keyword parameters} given When \keyref{key} is given in a \declref{function} \term{type specifier} \term{lambda list}, the \term{keyword parameters} given are exhaustive unless \keyref{allow-other-keys} is also present. \keyref{allow-other-keys} is an indication that other keyword arguments might actually be supplied and, if supplied, can be used. For example, the \term{type} of \thefunction{make-list} could be declared as follows: \code (function ((integer 0) &key (:initial-element t)) list) \endcode \endissue{FUNCTION-TYPE-KEY-NAME:SPECIFY-KEYWORD} The \param{value-type} can be a \declref{values} \term{type specifier} in order to indicate the \term{types} of \term{multiple values}. \issue{FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS:RESTRICTIVE} %{The following will be deleted:} % % %%% 4.5.0 13 %For example, \thefunction{cons} is of type \f{(function (t t) cons)}, %because it can accept any two arguments and always returns a \term{cons}. %%%see FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS; cons isn't of the following type. %\funref{cons} is also of type {\tt (function (float string) list)}, %because it can %accept a \term{float} %and a \term{string} (among other things), and its %result is always \oftype{list} %(in fact a \term{cons} is never \term{null}, %but that does not matter for this type declaration). %\funref{truncate} is of type %{\tt (function (number number) (values number number))}, %as well as of type %{\tt (function (integer (mod 8)) integer)}. % %{End of deletion.} Consider a declaration of the following form: \code (ftype (function (arg0-type arg1-type ...) val-type) f)) \endcode Any \term{form} {\tt (f arg0 arg1 ...)} within the scope of that declaration is equivalent to the following: \code (the val-type (f (the arg0-type arg0) (the arg1-type arg1) ...)) \endcode That is, the consequences are undefined if any of the arguments are not of the specified \term{types} or the result is not of the specified \term{type}. In particular, if any argument is not of the correct \term{type}, the result is not guaranteed to be of the specified \term{type}. Thus, an \declref{ftype} declaration for a \term{function} describes \term{calls} to the \term{function}, not the actual definition of the \term{function}. Consider a declaration of the following form: \code (type (function (arg0-type arg1-type ...) val-type) fn-valued-variable) \endcode This declaration has the interpretation that, within the scope of the declaration, the consequences are unspecified if the value of {\tt fn-valued-variable} is called with arguments not of the specified \term{types}; the value resulting from a valid call will be of type {\tt val-type}. As with variable type declarations, nested declarations imply intersections of \term{types}, as follows: \beginlist \itemitem{\bull} Consider the following two declarations of \declref{ftype}: \code (ftype (function (arg0-type1 arg1-type1 ...) val-type1) f)) \endcode and \code (ftype (function (arg0-type2 arg1-type2 ...) val-type2) f)) \endcode If both these declarations are in effect, then within the shared scope of the declarations, calls to {\tt f} can be treated as if {\tt f} were declared as follows: \code (ftype (function ((and arg0-type1 arg0-type2) (and arg1-type1 arg1-type2 ...) ...) (and val-type1 val-type2)) f)) \endcode %!!! Barmar: what does this mean? % KMP: This is ill-worded and out of place. It is permitted to ignore one or all of the \declref{ftype} declarations in force. \itemitem{\bull} If two (or more) type declarations are in effect for a variable, and they are both {\tt function} declarations, the declarations combine similarly. \endlist \endissue{FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS:RESTRICTIVE} \endissue{FUNCTION-TYPE:X3J13-MARCH-88} \endcom%{function}\ftype{System Class} %%% ========== COMPILED-FUNCTION \begincom{compiled-function}\ftype{Type} \issue{FUNCTION-TYPE:X3J13-MARCH-88} \label Supertypes:: \typeref{compiled-function}, \typeref{function}, \typeref{t} \label Description:: \issue{COMPILED-FUNCTION-REQUIREMENTS:TIGHTEN} Any \term{function} may be considered by an \term{implementation} to be a a \term{compiled function} if it contains no references to \term{macros} that must be expanded at run time, and it contains no unresolved references to \term{load time values}. \Seesection\CompilationSemantics. \endissue{COMPILED-FUNCTION-REQUIREMENTS:TIGHTEN} %% 2.13.0 2 \term{Functions} whose definitions appear lexically within a \term{file} that has been \term{compiled} with \funref{compile-file} and then \term{loaded} with \funref{load} are \oftype{compiled-function}. \issue{COMPILED-FUNCTION-REQUIREMENTS:TIGHTEN} \term{Functions} produced by the \funref{compile} function are \oftype{compiled-function}. \endissue{COMPILED-FUNCTION-REQUIREMENTS:TIGHTEN} Other \term{functions} might also be \oftype{compiled-function}. %but \funref{compile} does not necessarily produce a \term{compiled function}. \endissue{FUNCTION-TYPE:X3J13-MARCH-88} \endcom%{compiled-function}\ftype{Type} %%% ========== GENERIC-FUNCTION \begincom{generic-function}\ftype{System Class} \issue{JUN90-TRIVIAL-ISSUES:9} \label Class Precedence List:: \typeref{generic-function}, \typeref{function}, \typeref{t} \endissue{JUN90-TRIVIAL-ISSUES:9} \label Description:: A \newterm{generic function} is a \term{function} whose behavior depends on the \term{classes} or identities of the \term{arguments} supplied to it. A generic function object contains a set of \term{methods}, a \term{lambda list}, a \term{method combination} \term{type}, and other information. The \term{methods} define the class-specific behavior and operations of the \term{generic function}; a \term{method} is said to \term{specialize} a \term{generic function}. When invoked, a \term{generic function} executes a subset of its \term{methods} based on the \term{classes} or identities of its \term{arguments}. A \term{generic function} can be used in the same ways that an ordinary \term{function} can be used; specifically, a \term{generic function} can be used as an argument to \funref{funcall} and \funref{apply}, and can be given a global or a local name. \endcom%{generic-function}\ftype{System Class} %%% ========== STANDARD-GENERIC-FUNCTION \begincom{standard-generic-function}\ftype{System Class} \label Class Precedence List:: \typeref{standard-generic-function}, \typeref{generic-function}, \typeref{function}, \typeref{t} \label Description:: \Theclass{standard-generic-function} is the default \term{class} of \term{generic functions} \term{established} by \macref{defmethod}, \funref{ensure-generic-function}, \macref{defgeneric}, \issue{GENERIC-FLET-POORLY-DESIGNED:DELETE} % \macref{generic-function}, % \specref{generic-flet}, % \specref{generic-labels}, \endissue{GENERIC-FLET-POORLY-DESIGNED:DELETE} \issue{WITH-ADDED-METHODS:DELETE} %\specref{with-added-methods}, \endissue{WITH-ADDED-METHODS:DELETE}% and \macref{defclass} \term{forms}. \endcom%{standard-generic-function}\ftype{System Class} %random-state moved to dict-numbers %conditions moved to dict-conditions, some perhaps to move again %%% ========== CLASS \begincom{class}\ftype{System Class} \issue{JUN90-TRIVIAL-ISSUES:9} \label Class Precedence List:: \typeref{class}, \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{standard-object}, \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{t} \endissue{JUN90-TRIVIAL-ISSUES:9} \label Description:: %!!! Barrett: Since none of this can be accessed portably, % why specifically mention any of it? \Thetype{class} represents \term{objects} that determine the structure and behavior of their \term{instances}. Associated with an \term{object} \oftype{class} is information describing its place in the directed acyclic graph of \term{classes}, its \term{slots}, and its options. %% Barrett: No! This is a gross AMOPism. %and information about the \term{methods} that mention this \term{class} as a specializer. % I had a terrible time figuring out what these paragraphs were trying % to say until I realized what cleanup issue they were from. I've moved % this text to the discussion of built-in types in the classes concepts % section, where there is more context for it. --sjl 7 Mar 92 %\issue{CONDITION-SLOTS:HIDDEN} %It is \term{implementation-dependent} whether \term{slots} are involved in the %operation of \term{functions} defined in this specification %on \term{instances} of \term{classes} defined in this specification, %except when \term{slots} are explicitly defined by this specification. % %If in a particular \term{implementation} a \term{class} defined in this specification %has \term{slots} that are not defined by this specfication, the names of these \term{slots} %must not be \term{external symbols} of \term{packages} defined in this specification nor %otherwise \term{accessible} in \thepackage{cl-user}. %\endissue{CONDITION-SLOTS:HIDDEN} \endcom%{class}\ftype{System Class} %%% ========== BUILT-IN-CLASS \begincom{built-in-class}\ftype{System Class} \label Class Precedence List:: \typeref{built-in-class}, \typeref{class}, \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{standard-object}, \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{t} \label Description:: A \term{built-in class} is a \term{class} whose \term{instances} have restricted capabilities or special representations. %!!! Barrett: The rest of this looks like a duplication of text a few pages back. Attempting to use \macref{defclass} to define \term{subclasses} of a \term{built-in class} signals an error \oftype{error}. Calling \funref{make-instance} to create an \term{instance} of a \term{built-in class} signals an error \oftype{error}. Calling \funref{slot-value} on an \term{instance} of a \term{built-in class} signals an error \oftype{error}. Redefining a \term{built-in class} or using \funref{change-class} to change the \term{class} of an \term{instance} to or from a \term{built-in class} signals an error \oftype{error}. However, \term{built-in classes} can be used as \term{parameter specializers} in \term{methods}. %!!! Barrett: Other ops also signal errors. % See SLOT-VALUE-METACLASSES %Any \term{class} that corresponds to a standard %\clisp\ type specified in \CLtL\ %might be an instance of \typeref{built-in-class}. %The predefined Common Lisp \term{type specifiers} that are required to have %corresponding classes are listed in \figref\ClassTypeCorrespondence. It is implementation %dependent whether each of these classes is implemented as a built-in class. \endcom%{built-in-class}\ftype{System Class} %%% ========== STRUCTURE-CLASS \begincom{structure-class}\ftype{System Class} \label Class Precedence List:: \typeref{structure-class}, \typeref{class}, \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{standard-object}, \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{t} \label Description:: All \term{classes} defined by means of \macref{defstruct} are \instsofclass{structure-class}. \endcom%{structure-class}\ftype{System Class} %%% ========== STANDARD-CLASS \begincom{standard-class}\ftype{System Class} \label Class Precedence List:: \typeref{standard-class}, \typeref{class}, \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{standard-object}, \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{t} \label Description:: \Theclass{standard-class} is the default \term{class} of \term{classes} defined by \macref{defclass}. \endcom%{standard-class}\ftype{System Class} %%% ========== METHOD \begincom{method}\ftype{System Class} \issue{JUN90-TRIVIAL-ISSUES:9} \label Class Precedence List:: \typeref{method}, \typeref{t} \endissue{JUN90-TRIVIAL-ISSUES:9} \label Description:: A \term{method} is an \term{object} that represents a modular part of the behavior of a \term{generic function}. A \term{method} contains \term{code} to implement the \term{method}'s behavior, a sequence of \term{parameter specializers} that specify when the given \term{method} is applicable, and a sequence of \term{qualifiers} that is used by the method combination facility to distinguish among \term{methods}. Each required parameter of each \term{method} has an associated \term{parameter specializer}, and the \term{method} will be invoked only on arguments that satisfy its \term{parameter specializers}. The method combination facility controls the selection of \term{methods}, the order in which they are run, and the values that are returned by the generic function. The \CLOS\ offers a default method combination type and provides a facility for declaring new types of method combination. \label See Also:: {\secref\GFsAndMethods} \endcom%{method}\ftype{System Class} %%% ========== STANDARD-METHOD \begincom{standard-method}\ftype{System Class} \label Class Precedence List:: \typeref{standard-method}, \typeref{method}, \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{standard-object}, \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{t} \label Description:: \Theclass{standard-method} is the default \term{class} of \term{methods} defined by the \macref{defmethod} and \macref{defgeneric} \term{forms}. \issue{GENERIC-FLET-POORLY-DESIGNED:DELETE} % \macref{generic-function}, \endissue{GENERIC-FLET-POORLY-DESIGNED:DELETE} \issue{WITH-ADDED-METHODS:DELETE} %\specref{with-added-methods}, \endissue{WITH-ADDED-METHODS:DELETE}% % \specref{generic-flet}, % and % \specref{generic-labels} \term{forms}. \endcom%{standard-method}\ftype{System Class} %%% ========== STRUCTURE-OBJECT \begincom{structure-object}\ftype{Class} \issue{JUN90-TRIVIAL-ISSUES:9} \label Class Precedence List:: \typeref{structure-object}, \typeref{t} \endissue{JUN90-TRIVIAL-ISSUES:9} \label Description:: % \Theclass{structure-object} is a \term{superclass} of % every \term{class} that is defined by \macref{defstruct}. \Theclass{structure-object} is an \term{instance} of \typeref{structure-class} and is a \term{superclass} of every \term{class} that is an \term{instance} of \typeref{structure-class} except itself, and is a \term{superclass} of every \term{class} that is defined by \macref{defstruct}. \issue{DATA-TYPES-HIERARCHY-UNDERSPECIFIED}% %% Barrett: This is bogus. I think there is enough other text in the draft %% (the first bullet in ``Type Relationships'' plus the definition of %% \term{system class}) to cover the requirements specified by %% DATA-TYPES-HIERARCHY-UNDERSPECIFIED that this could simply be removed. % The following \term{type specifier} \term{symbols} do not name % \term{structure} \term{types} in any \term{implementation}: % \typeref{cons}, \typeref{symbol}, \typeref{array}, % \typeref{number}, % \typeref{character}, \typeref{hash-table}, % \typeref{readtable}, \typeref{package}, \typeref{pathname}, % \typeref{stream}, or % \typeref{random-state}. % It is \term{implementation-dependent} % whether other \term{standardized} \term{type specifiers} name structure types. \endissue{DATA-TYPES-HIERARCHY-UNDERSPECIFIED} \label See Also:: \macref{defstruct}, {\secref\SharpsignS}, {\secref\PrintingStructures} \endcom%{structure-object}\ftype{Class} %%% ========== STANDARD-OBJECT \begincom{standard-object}\ftype{Class} \label Class Precedence List:: \typeref{standard-object}, \typeref{t} \label Description:: \Theclass{standard-object} is an \term{instance} of \typeref{standard-class} and is a \term{superclass} of every \term{class} that is an \term{instance} of \typeref{standard-class} except itself. % and %\typeref{structure-class}. \endcom%{standard-object}\ftype{Class} %%% ========== METHOD-COMBINATION \begincom{method-combination}\ftype{System Class} \label Class Precedence List:: \typeref{method-combination}, \typeref{t} \label Description:: Every \term{method combination} \term{object} is an \term{indirect instance} of the \term{class} \typeref{method-combination}. A \term{method combination} \term{object} represents the information about the \term{method combination} being used by a \term{generic function}. A \term{method combination} \term{object} contains information about both the type of \term{method combination} and the arguments being used with that \term{type}. \endcom%{method-combination}\ftype{System Class} %%% ========== T %% 2.0.0 6 \begincom{t}\ftype{System Class} \label Class Precedence List:: \typeref{t} \label Description:: The set of all \term{objects}. %% 2.15.0 4 \Thetype{t} is a \term{supertype} of every \term{type}, including itself. Every \term{object} is \oftype{t}. \issue{COMMON-TYPE:REMOVE} % Reference to type COMMON removed, and moved to Appendix A. \endissue{COMMON-TYPE:REMOVE} \endcom%{t}\ftype{System Class} %%% ========== SATISFIES \begincom{satisfies}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Predicating. \label Compound Type Specifier Syntax:: \Deftype{satisfies}{predicate-name} \label Compound Type Specifier Arguments:: \param{predicate-name}---a \term{symbol}. \label Compound Type Specifier Description:: %% 4.3.0 1 %\itemitem %{\tt (satisfies \param{predicate-name})} This denotes the set of all \term{objects} that satisfy the \term{predicate} \param{predicate-name}, which must be a \term{symbol} whose global \term{function} definition is a one-argument predicate. A name is required for \param{predicate-name}; \term{lambda expressions} are not allowed. For example, the \term{type specifier} {\tt (and integer (satisfies evenp))} denotes the set of all even integers. The form {\tt (typep \param{x} '(satisfies \param{p}))} is equivalent to {\tt (if (\param{p} \param{x}) t nil)}. % The call {\tt (typep x '(satisfies p))} results in applying % \f{p} to \f{x} and returning \f{t} if the result is \term{true} and \nil\ if the % result is \term{false}. %% 4.3.0 2 %% I don't like the following example because it presupposes that standard-char-p is not % defined in terms of typep. -kmp 24-Oct-90 % For example, \thetype{standard-char} could be defined as follows: % % \code % (deftype standard-char () '(and character (satisfies standard-char-p))) % \endcode \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} The argument is required. The \term{symbol} \misc{*} can be the argument, but it denotes itself (the \term{symbol} \misc{*}), and does not represent an unspecified value. The symbol \typeref{satisfies} is not valid as a \term{type specifier}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \endcom%{satisfies}\ftype{Type Specifier} %%% ========== MEMBER \begincom{member}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Combining. \label Compound Type Specifier Syntax:: \Deftype{member}{\starparam{object}} \label Compound Type Specifier Arguments:: \param{object}---an \term{object}. \label Compound Type Specifier Description:: %% 4.4.0 3 %\itemitem %{\tt (member \starparam{object})} %{\tt (member \param{object1} \param{object2} ...)} This denotes the set containing the named \param{objects}. An \term{object} is of this \term{type} if and only if it is \funref{eql} to one of the specified \param{objects}. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} The \term{type specifiers} \f{(member)} and \nil\ are equivalent. \misc{*} can be among the \param{objects}, but if so it denotes itself (the symbol \misc{*}) and does not represent an unspecified value. The symbol \misc{member} is not valid as a \term{type specifier}; and, specifically, it is not an abbreviation for either \f{(member)} or \f{(member *)}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \label See Also:: \thetype{eql} \endcom%{member}\ftype{Type Specifier} %%% ========== NOT \begincom{not}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Combining. \label Compound Type Specifier Syntax:: %% 4.4.0 4 \Deftype{not}{typespec} \label Compound Type Specifier Arguments:: \param{typespec}---a \term{type specifier}. \label Compound Type Specifier Description:: This denotes the set of all \term{objects} that are not of the \term{type} \param{typespec}. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} The argument is required, and cannot be \misc{*}. The symbol \typeref{not} is not valid as a \term{type specifier}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \endcom%{not}\ftype{Type Specifier} %%% ========== AND \begincom{and}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Combining. \label Compound Type Specifier Syntax:: %% 4.4.0 5 \Deftype{and}{\starparam{typespec}} \label Compound Type Specifier Arguments:: \param{typespec}---a \term{type specifier}. \label Compound Type Specifier Description:: This denotes the set of all \term{objects} of the \term{type} determined by the intersection of the \param{typespecs}. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \misc{*} is not permitted as an argument. The \term{type specifiers} \f{(and)} and \t\ are equivalent. The symbol \misc{and} is not valid as a \term{type specifier}, and, specifically, it is not an abbreviation for \f{(and)}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \endcom%{and}\ftype{Type Specifier} %%% ========== OR \begincom{or}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Combining. \label Compound Type Specifier Syntax:: %% 4.4.0 7 \Deftype{or}{\starparam{typespec}} \label Compound Type Specifier Arguments:: \param{typespec}---a \term{type specifier}. \label Compound Type Specifier Description:: This denotes the set of all \term{objects} of the \term{type} determined by the union of the \param{typespecs}. For example, \thetype{list} by definition is the same as \f{(or null cons)}. Also, the value returned by \funref{position} is an \objectoftype{(or null (integer 0 *))}; \ie either \nil\ or a non-negative \term{integer}. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \misc{*} is not permitted as an argument. The \term{type specifiers} \f{(or)} and \nil\ are equivalent. The symbol \typeref{or} is not valid as a \term{type specifier}; and, specifically, it is not an abbreviation for \f{(or)}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \endcom%{or}\ftype{Type Specifier} %%% ========== VALUES \begincom{values}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Specializing. \label Compound Type Specifier Syntax:: \Deftype{values}{\down{value-typespec}} \reviewer{Barmar: Missing \keyref{key}}%!!! \auxbnf{value-typespec}{\starparam{typespec} \ttbrac{{\opt} {\starparam{typespec}}} \ttbrac{{\rest} typespec} \ttbrac{\keyref{allow-other-keys}}} \label Compound Type Specifier Arguments:: \param{typespec}---a \term{type specifier}. \label Compound Type Specifier Description:: %% 4.5.0 14 %\itemitem{\tt (values \starparam{value-type})} %\itemitem{\tt (values \param{value1-type} \param{value2-type} ...)} This \term{type specifier} can be used only as the \param{value-type} in a \typeref{function} \term{type specifier} or a \specref{the} \term{special form}. It is used to specify individual \term{types} when \term{multiple values} are involved. The \keyref{optional} and \keyref{rest} markers can appear in the \param{value-type} list; they indicate the parameter list of a \term{function} that, when given to \specref{multiple-value-call} along with the values, %would be suitable for receiving those values. would correctly receive those values. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} The symbol \misc{*} may not be among the \param{value-types}. The symbol \misc{values} is not valid as a \term{type specifier}; and, specifically, it is not an abbreviation for \f{(values)}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \endcom%{values}\ftype{Type Specifier} %%% ========== EQL \begincom{eql}\ftype{Type Specifier} \label Compound Type Specifier Kind:: Combining. \label Compound Type Specifier Syntax:: \Deftype{eql}{object} \label Compound Type Specifier Arguments:: \param{object}---an \term{object}. \label Compound Type Specifier Description:: Represents the \term{type} %% Replaced per Boyer/Kaufmann/Moore #6 (by X3J13 vote at May 4-5, 1994 meeting). %whose only \term{element} is \param{object}. of all \param{x} for which \f{(eql \param{object} \param{x})} is true. \issue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} The argument \param{object} is required. The \param{object} can be \misc{*}, but if so it denotes itself (the symbol \misc{*}) and does not represent an unspecified value. The \term{symbol} \misc{eql} is not valid as an \term{atomic type specifier}. %% Laubsch thinks this second part is gratuitous (and I agree). -kmp 20-Jan-92 %and, specifically, it is not an abbreviation for \f{(eql *)}. \endissue{TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS} \endcom%{eql}\ftype{Type Specifier} %%% ========== COERCE \begincom{coerce}\ftype{Function} \label Syntax:: \DefunWithValues coerce {object result-type} {result} \label Arguments and Values:: \param{object}---an \term{object}. \param{result-type}---a \term{type specifier}. \param{result}---an \term{object}, of \term{type} \param{result-type} except in situations described in \secref\RuleOfCanonRepForComplexRationals. \label Description:: %% 4.8.0 3 \term{Coerces} the \param{object} to \term{type} \param{result-type}. If \param{object} is already of \term{type} \param{result-type}, the \param{object} itself is returned, regardless of whether it would have been possible in general to coerce an \term{object} of some other \term{type} to \param{result-type}. %% 4.8.0 4 Otherwise, the \param{object} is \term{coerced} to \term{type} \param{result-type} according to the following rules: \beginlist \itemitem{\typeref{sequence}} \issue{CONCATENATE-SEQUENCE:SIGNAL-ERROR} % If the \param{result-type} is a \term{subtype} of \typeref{list}, % the result will be a \term{list}. % % If the \param{result-type} is a \term{subtype} of \typeref{vector}, % then if the implementation can determine the element type specified % for the \param{result-type}, the element type of the resulting array % is the result of \term{upgrading} that element type; or, if the % implementation can determine that the element type is unspecified (or \f{*}), % the element type of the resulting array is \typeref{t}; % otherwise, an error is signaled. If the \param{result-type} is a \term{recognizable subtype} of \typeref{list}, and the \term{object} is a \term{sequence}, then the \param{result} is a \term{list} that has the \term{same} \term{elements} as \param{object}. If the \param{result-type} is a \term{recognizable subtype} of \typeref{vector}, and the \term{object} is a \term{sequence}, then the \param{result} is a \term{vector} that has the \term{same} \term{elements} as \param{object}. If \param{result-type} is a specialized \term{type}, the \param{result} has an \term{actual array element type} that is the result of \term{upgrading} the element type part of that \term{specialized} \term{type}. If no element type is specified, the element type defaults to \typeref{t}. If the \term{implementation} cannot determine the element type, an error is signaled. % I don't understand this and I can't figure out where it came from. % It's stated below that an error is signaled if the appropriate result % cannot be constructed. --sjl 7 Mar 92 %The consequences are undefined if the \param{result} is not of \term{type} %\param{result-type}. \endissue{CONCATENATE-SEQUENCE:SIGNAL-ERROR} \itemitem{\typeref{character}} If the \param{result-type} is \typeref{character} and the \term{object} is a \term{character designator}, the \param{result} is the \term{character} it denotes. \issue{CHARACTER-LOOSE-ENDS:FIX} %Reference to INT-CHAR removed. \endissue{CHARACTER-LOOSE-ENDS:FIX} \itemitem{\typeref{complex}} %% 4.8.0 7 If the \param{result-type} is \typeref{complex} %% "number" => "real" per Boyer/Kaufmann/Moore #7 (by X3J13 vote at May 4-5, 1994 meeting) %% -kmp 9-May-94 and the \term{object} is a \term{real}, then the \param{result} is obtained by constructing a \term{complex} whose real part is the \term{object} and whose imaginary part is the result of \term{coercing} an \term{integer} zero to the \term{type} of the \term{object} (using \funref{coerce}). (If the real part is a \term{rational}, however, then the result must be represented as a \term{rational} rather than a \term{complex}; \seesection\RuleOfCanonRepForComplexRationals. So, for example, \f{(coerce 3 'complex)} is permissible, but will return \f{3}, which is not a \term{complex}.) \itemitem{\typeref{float}} %% 4.8.0 6 If the \param{result-type} is any of \typeref{float}, \typeref{short-float}, \typeref{single-float}, \typeref{double-float}, \typeref{long-float}, and the \term{object} is a \issue{REAL-NUMBER-TYPE:X3J13-MAR-89} \term{real}, \endissue{REAL-NUMBER-TYPE:X3J13-MAR-89} then the \param{result} is a \term{float} of \term{type} \param{result-type} which is equal in sign and magnitude to the \term{object} to whatever degree of representational precision is permitted by that \term{float} representation. (If the \param{result-type} is \typeref{float} and \param{object} is not already a \term{float}, then the \param{result} is a \term{single float}.) \issue{FUNCTION-TYPE:X3J13-MARCH-88} \itemitem{\typeref{function}} If the \param{result-type} is \typeref{function}, and \param{object} is any \issue{COERCING-SETF-NAME-TO-FUNCTION:ALL-FUNCTION-NAMES} %% Barmar asked what about (COERCE '(SETF symbol) 'FUNCTION) %% Mail sent to Quinquevirate. -kmp 3-Jun-91 %% This change was the result of that discussion. kmp 14-May-93 %\term{symbol} \term{function name} \endissue{COERCING-SETF-NAME-TO-FUNCTION:ALL-FUNCTION-NAMES} that is \term{fbound} but that is globally defined neither as a \term{macro name} nor as a \term{special operator}, then the \param{result} is the \term{functional value} of \param{object}. If the \param{result-type} is \typeref{function}, and \param{object} is a \term{lambda expression}, then the \param{result} is a \term{closure} of \param{object} in the \term{null lexical environment}. \endissue{FUNCTION-TYPE:X3J13-MARCH-88} \itemitem{\typeref{t}} %% 4.8.0 8 Any \param{object} can be \term{coerced} to an \term{object} \oftype{t}. In this case, the \param{object} is simply returned. \endlist \label Examples:: \code (coerce '(a b c) 'vector) \EV #(A B C) (coerce 'a 'character) \EV #\\A (coerce 4.56 'complex) \EV #C(4.56 0.0) (coerce 4.5s0 'complex) \EV #C(4.5s0 0.0s0) (coerce 7/2 'complex) \EV 7/2 (coerce 0 'short-float) \EV 0.0s0 (coerce 3.5L0 'float) \EV 3.5L0 (coerce 7/2 'float) \EV 3.5 (coerce (cons 1 2) t) \EV (1 . 2) \endcode \issue{SEQUENCE-TYPE-LENGTH:MUST-MATCH} All the following \term{forms} should signal an error: \code (coerce '(a b c) '(vector * 4)) (coerce #(a b c) '(vector * 4)) (coerce '(a b c) '(vector * 2)) (coerce #(a b c) '(vector * 2)) (coerce "foo" '(string 2)) (coerce #(#\\a #\\b #\\c) '(string 2)) (coerce '(0 1) '(simple-bit-vector 3)) \endcode \endissue{SEQUENCE-TYPE-LENGTH:MUST-MATCH} \label Affected By:\None. \label Exceptional Situations:: If a coercion is not possible, an error \oftype{type-error} is signaled. \f{(coerce x 'nil)} always signals an error \oftype{type-error}. An error %KMP: I'm not sure UNDEFINED-FUNCTION is the right error type to signal here. %Barrett: Yeah. This isn't really right for `fbound but not function'. Make it ERROR. %KMP: Done \oftype{error} is signaled if the \param{result-type} is \typeref{function} but \param{object} is a \term{symbol} that is not \term{fbound} or if the \term{symbol} names a \term{macro} or a \term{special operator}. \issue{SEQUENCE-TYPE-LENGTH:MUST-MATCH} An error \oftype{type-error} should be signaled if \param{result-type} specifies the number of elements and \param{object} is of a different length. \endissue{SEQUENCE-TYPE-LENGTH:MUST-MATCH} \label See Also:: \funref{rational}, \funref{floor}, \funref{char-code}, \funref{char-int} \label Notes:: %% 4.8.0 9 Coercions from \term{floats} to \term{rationals} and from \term{ratios} to \term{integers} are not provided because of rounding problems. \code (coerce x 't) \EQ (identity x) \EQ x \endcode \endcom %%% ========== DEFTYPE \begincom{deftype}\ftype{Macro} \issue{DECLS-AND-DOC} \label Syntax:: \DefmacWithValues deftype {name lambda-list {\DeclsAndDoc} \starparam{form}} {name} \label Arguments and Values:: \param{name}---a \term{symbol}. \param{lambda-list}---a \term{deftype lambda list}. \param{declaration}---a \misc{declare} \term{expression}; \noeval. %% 4.7.0 4 \param{documentation}---a \term{string}; \noeval. \param{form}---a \term{form}. \label Description:: %% 4.7.0 2 \funref{deftype} defines a \term{derived type specifier} named \param{name}. The meaning of the new \term{type specifier} is given in terms of %tweaked --sjl 7 Mar 92 %a body of code which expands the \term{type specifier} into another a function which expands the \term{type specifier} into another \term{type specifier}, which itself will be expanded if it contains references to another \term{derived type specifier}. The newly defined \term{type specifier} may be referenced as a list of the form {\tt (\param{name} \param{arg$\sub{1}$} \param{arg$\sub{2}$} ...)\/}. The number of arguments must be appropriate to the \param{lambda-list}. If the new \term{type specifier} takes no arguments, or if all of its arguments are optional, the \term{type specifier} may be used as an \term{atomic type specifier}. The \term{argument} \term{expressions} to the \term{type specifier}, \param{arg$\sub{1}$} $\ldots$ \param{arg$\sub{n}$}, are not \term{evaluated}. Instead, these \term{literal objects} become the \term{objects} to which corresponding \term{parameters} become \term{bound}. The body of the \funref{deftype} \term{form} \issue{DEFMACRO-BLOCK-SCOPE:EXCLUDES-BINDINGS} (but not the \param{lambda-list}) \endissue{DEFMACRO-BLOCK-SCOPE:EXCLUDES-BINDINGS} is \issue{FLET-IMPLICIT-BLOCK:YES} implicitly enclosed in a \term{block} named \param{name}, \endissue{FLET-IMPLICIT-BLOCK:YES} and is evaluated as an \term{implicit progn}, returning a new \term{type specifier}. \issue{DEFINING-MACROS-NON-TOP-LEVEL:ALLOW} The \term{lexical environment} of the body is the one which was current at the time the \macref{deftype} form was evaluated, augmented by the \term{variables} in the \param{lambda-list}. \endissue{DEFINING-MACROS-NON-TOP-LEVEL:ALLOW} \issue{RECURSIVE-DEFTYPE:EXPLICITLY-VAGUE} Recursive expansion of the \term{type specifier} returned as the expansion must terminate, including the expansion of \term{type specifiers} which are nested within the expansion. The consequences are undefined if the result of fully expanding a \term{type specifier} contains any circular structure, except within the \term{objects} referred to by \typeref{member} and \typeref{eql} \term{type specifiers}. \endissue{RECURSIVE-DEFTYPE:EXPLICITLY-VAGUE} %% 4.7.0 4 \param{Documentation} is attached to \param{name} as a \term{documentation string} of kind \misc{type}. \issue{COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY} % added qualification about top-level-ness --sjl 5 Mar 92 If a \macref{deftype} \term{form} appears as a \term{top level form}, the \term{compiler} must ensure that the \param{name} is recognized in subsequent \term{type} declarations. The \term{programmer} must ensure that the body of a \macref{deftype} form can be \term{evaluated} at compile time if the \param{name} is referenced in subsequent \term{type} declarations. If the expansion of a \term{type specifier} is not defined fully at compile time (perhaps because it expands into an unknown \term{type specifier} or a \declref{satisfies} of a named \term{function} that isn't defined in the compile-time environment), an \term{implementation} may ignore any references to this \term{type} in declarations and/or signal a warning. \endissue{COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY} \label Examples:: %% 4.7.0 5 \code (defun equidimensional (a) (or (< (array-rank a) 2) (apply #'= (array-dimensions a)))) \EV EQUIDIMENSIONAL (deftype square-matrix (&optional type size) `(and (array ,type (,size ,size)) (satisfies equidimensional))) \EV SQUARE-MATRIX \endcode \label Side Effects:\None. \label Affected By:\None. \label Exceptional Situations:\None. % addressed in the packages chapter. --sjl 5 Mar 92 %\issue{LISP-SYMBOL-REDEFINITION:MAR89-X3J13} %The consequences are undefined if a \term{symbol} in \thepackage{common-lisp} %is used as the \param{name} argument. %\endissue{LISP-SYMBOL-REDEFINITION:MAR89-X3J13} \label See Also:: \misc{declare}, \macref{defmacro}, \funref{documentation}, {\secref\TypeSpecifiers}, {\secref\DocVsDecls} \label Notes:\None. \endissue{DECLS-AND-DOC} \endcom %%% ========== SUBTYPEP \begincom{subtypep}\ftype{Function} \issue{SUBTYPEP-ENVIRONMENT:ADD-ARG} \label Syntax:: \DefunWithValues subtypep {type-1 type-2 {\opt} environment} {subtype-p, valid-p} \label Arguments and Values:: \param{type-1}---a \term{type specifier}. % acceptable to \funref{typep} \param{type-2}---a \term{type specifier}. % acceptable to \funref{typep}. %!!! as opposed to what? need a glossary term -kmp 15-Feb-91 \param{environment}---an \term{environment} \term{object}. \Default{\nil, denoting the \term{null lexical environment} and the current \term{global environment}} %!!! Need to say what happens with the environment. \param{subtype-p}---a \term{generalized boolean}. \param{valid-p}---a \term{generalized boolean}. \label Description:: %% 6.2.1 3 If \param{type-1} is a \term{recognizable subtype} of \param{type-2}, the first \term{value} is \term{true}. Otherwise, the first \term{value} is \term{false}, indicating that either \param{type-1} is not a \term{subtype} of \param{type-2}, or else \param{type-1} is a \term{subtype} of \param{type-2} but is not a \term{recognizable subtype}. A second \term{value} is also returned indicating the `certainty' of the first \term{value}. If this value is \term{true}, then the first value is an accurate indication of the \term{subtype} relationship. (The second \term{value} is always \term{true} when the first \term{value} is \term{true}.) \Thenextfigure\ summarizes the possible combinations of \term{values} that might result. \tablefigthree{Result possibilities for subtypep}{Value 1}{Value 2}{Meaning}{ \term{true} & \term{true} & \param{type-1} is definitely a \term{subtype} of \param{type-2}.\cr \term{false} & \term{true} & \param{type-1} is definitely not a \term{subtype} of \param{type-2}.\cr \term{false} & \term{false} & \funref{subtypep} could not determine the relationship,\cr & & so \param{type-1} might or might not be a \term{subtype} of \param{type-2}.\cr } \issue{SUBTYPEP-TOO-VAGUE:CLARIFY-MORE} \funref{subtypep} is permitted to return the \term{values} \term{false} and \term{false} only when at least one argument involves one of these \term{type specifiers}: \declref{and}, % Added per Barrett: \declref{eql}, the list form of \declref{function}, \declref{member}, \declref{not}, \declref{or}, \declref{satisfies}, or \declref{values}. (A \term{type specifier} `involves' such a \term{symbol} if, after being \term{type expanded}, it contains that \term{symbol} in a position that would call for its meaning as a \term{type specifier} to be used.) One consequence of this is that if neither \param{type-1} nor \param{type-2} involves any of these \term{type specifiers}, then \funref{subtypep} is obliged to determine the relationship accurately. In particular, \funref{subtypep} returns the \term{values} \term{true} and \term{true} if the arguments are \funref{equal} and do not involve any of these \term{type specifiers}. \funref{subtypep} never returns a second value of \nil\ when both \param{type-1} and \param{type-2} involve only the names in \figref\StandardizedAtomicTypeSpecs, or names of \term{types} defined by \macref{defstruct}, \macref{define-condition}, or \macref{defclass}, or \term{derived types} that expand into only those names. While \term{type specifiers} listed in \figref\StandardizedAtomicTypeSpecs\ and names of \macref{defclass} and \macref{defstruct} can in some cases be implemented as \term{derived types}, \funref{subtypep} regards them as primitive. The relationships between \term{types} reflected by \funref{subtypep} are those specific to the particular implementation. For example, if an implementation supports only a single type of floating-point numbers, in that implementation \f{(subtypep 'float 'long-float)} returns the \term{values} \term{true} and \term{true} (since the two \term{types} are identical). \endissue{SUBTYPEP-TOO-VAGUE:CLARIFY-MORE} \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} For all \param{T1} and \param{T2} other than \f{*}, \f{(array \param{T1})} and \f{(array \param{T2})} are two different \term{type specifiers} that always refer to the same sets of things if and only if they refer to \term{arrays} of exactly the same specialized representation, \ie if \f{(upgraded-array-element-type '\param{T1})} and \f{(upgraded-array-element-type '\param{T2})} return two different \term{type specifiers} that always refer to the same sets of \term{objects}. This is another way of saying that \f{`(array \param{type-specifier})} and \f{`(array ,(upgraded-array-element-type '\param{type-specifier}))} refer to the same set of specialized \term{array} representations. For all \param{T1} and \param{T2} other than \f{*}, %tweaked --sjl 7 Mar 92 %the specified intersection for % \f{(array \param{T1})} %and \f{(array \param{T2})} is \nil\ the intersection of \f{(array \param{T1})} and \f{(array \param{T2})} is the empty set if and only if they refer to \term{arrays} of different, distinct specialized representations. Therefore, \code (subtypep '(array T1) '(array T2)) \EV \term{true} \endcode if and only if \code (upgraded-array-element-type 'T1) and (upgraded-array-element-type 'T2) \endcode return two different \term{type specifiers} that always refer to the same sets of \term{objects}. For all type-specifiers \param{T1} and \param{T2} other than \f{*}, \code (subtypep '(complex T1) '(complex T2)) \EV \term{true}, \term{true} \endcode if: \beginlist \itemitem{1.} \f{T1} is a \term{subtype} of \f{T2}, or \itemitem{2.} \f{(upgraded-complex-part-type '\param{T1})} and \f{(upgraded-complex-part-type '\param{T2})} return two different \term{type specifiers} that always refer to the same sets of \term{objects}; in this case, \f{(complex \param{T1})} and \f{(complex \param{T2})} both refer to the same specialized representation. \endlist The \term{values} are \term{false} and \term{true} otherwise. The form \code (subtypep '(complex single-float) '(complex float)) \endcode must return \term{true} in all implementations, but \code (subtypep '(array single-float) '(array float)) \endcode returns \term{true} only in implementations that do not have a specialized \term{array} representation for \term{single floats} distinct from that for other \term{floats}. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} %% KAB: What?? % When a type description is restricted by range or enumeration, and the % restricted type is empty. \label Examples:: \code (subtypep 'compiled-function 'function) \EV \term{true}, \term{true} (subtypep 'null 'list) \EV \term{true}, \term{true} (subtypep 'null 'symbol) \EV \term{true}, \term{true} (subtypep 'integer 'string) \EV \term{false}, \term{true} (subtypep '(satisfies dummy) nil) \EV \term{false}, \term{implementation-dependent} (subtypep '(integer 1 3) '(integer 1 4)) \EV \term{true}, \term{true} (subtypep '(integer (0) (0)) 'nil) \EV \term{true}, \term{true} (subtypep 'nil '(integer (0) (0))) \EV \term{true}, \term{true} (subtypep '(integer (0) (0)) '(member)) \EV \term{true}, \term{true} ;or \term{false}, \term{false} (subtypep '(member) 'nil) \EV \term{true}, \term{true} ;or \term{false}, \term{false} (subtypep 'nil '(member)) \EV \term{true}, \term{true} ;or \term{false}, \term{false} \endcode \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} Let \f{} and \f{} be two distinct \term{type specifiers} that do not always refer to the same sets of \term{objects} in a given implementation, but for which \funref{make-array}, will return an \term{object} of the same \term{array} \term{type}. Thus, in each case, \code (subtypep (array-element-type (make-array 0 :element-type ')) (array-element-type (make-array 0 :element-type '))) \EV \term{true}, \term{true} (subtypep (array-element-type (make-array 0 :element-type ')) (array-element-type (make-array 0 :element-type '))) \EV \term{true}, \term{true} \endcode \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} If \f{(array )} and \f{(array )} are different names for exactly the same set of \term{objects}, these names should always refer to the same sets of \term{objects}. That implies that the following set of tests are also true: \code (subtypep '(array ) '(array )) \EV \term{true}, \term{true} (subtypep '(array ) '(array )) \EV \term{true}, \term{true} \endcode \label Side Effects:\None. \label Affected By:\None. \label Exceptional Situations:\None. \label See Also:: {\secref\Types} \label Notes:: \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} The small differences between the \funref{subtypep} specification for the \typeref{array} and \typeref{complex} types are necessary because there is no creation function for \term{complexes} which allows the specification of the resultant part type independently of the actual types of the parts. Thus in the case of \thetype{complex}, the actual type of the parts is referred to, although a \term{number} can be a member of more than one \term{type}. For example, \f{17} is of \term{type} \f{(mod 18)} as well as \term{type} \f{(mod 256)} and \term{type} \typeref{integer}; and \f{2.3f5} is \oftype{single-float} as well as \term{type} \typeref{float}. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} \endissue{SUBTYPEP-ENVIRONMENT:ADD-ARG} \endcom %%% ========== TYPE-OF \begincom{type-of}\ftype{Function} \label Syntax:: \DefunWithValues type-of {object} {typespec} \label Arguments and Values:: \param{object}---an \term{object}. \param{typespec}---a \term{type specifier}. \label Description:: \issue{TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS} Returns a \term{type specifier}, \param{typespec}, for a \term{type} that has the \param{object} as an \term{element}. The \param{typespec} satisfies the following: \beginlist \itemitem{1.} For any \param{object} that is an \term{element} of some \term{built-in type}: \beginlist \itemitem{a.} the \term{type} returned is a \term{recognizable subtype} of that \term{built-in type}. \itemitem{b.} %KMP: I added MEMBER and EQL because they seemed to be missing only by accident. % The discussion of TYPE-OF-UNDERCONSTRAINED seems to imply that MEMBER % is missing due to editing error. And I think EQL was added later. -kmp 3-Jun-91 the \term{type} returned does not involve \f{and}, \f{eql}, \f{member}, \f{not}, \f{or}, \f{satisfies}, or \f{values}. \endlist \itemitem{2.} For all \param{objects}, \f{(typep \param{object} (type-of \param{object}))} returns \term{true}. %Per Barmar: Implicit in this is that \term{type specifiers} which are not valid for use with \funref{typep}, such as the \term{list} form of the \funref{function} \term{type specifier}, are never returned by \funref{type-of}. \itemitem{3.} The \term{type} returned by \funref{type-of} is always a \term{recognizable subtype} of the \term{class} returned by \funref{class-of}. That is, \code (subtypep (type-of \param{object}) (class-of \param{object})) \EV \term{true}, \term{true} \endcode \itemitem{4.} For \param{objects} of metaclass \typeref{structure-class} or \typeref{standard-class}, \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} and for \term{conditions}, \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \funref{type-of} returns the \term{proper name} of the \term{class} returned by \funref{class-of} if it has a \term{proper name}, and otherwise returns the \term{class} itself. In particular, for \param{objects} created by the constructor function of a structure defined with \macref{defstruct} without a \kwd{type} option, \funref{type-of} returns the structure name; and for \param{objects} created by \funref{make-condition}, the \param{typespec} is the \term{name} of the \term{condition} \term{type}. \issue{TYPE-OF-AND-PREDEFINED-CLASSES:TYPE-OF-HANDLES-FLOATS} \itemitem{5.} For each of the \term{types} \typeref{short-float}, \typeref{single-float}, \typeref{double-float}, or \typeref{long-float} of which the \param{object} is an \term{element}, the \param{typespec} is a \term{recognizable subtype} of that \term{type}. \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:TYPE-OF-HANDLES-FLOATS} \endlist \endissue{TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS} %(The CLOS specification has already specified that class objects are %acceptable wherever \term{type specifiers} are, and in particular, as input to %SUBTYPEP and TYPEP.) % %This proposal is intended to be consistent with 88-002R, %and not to conflict with any of the definitions in that document. %If \param{object} is not a user-defined named %\term{structure} %created by \macref{defstruct}, %\funref{type-of} returns a \term{type} of which %\param{object} %is a member. %%% 4.9.0 3 %The result in this case is \term{implementation-dependent}. %For example: % %\code % (type-of "abc") \EV SIMPLE-STRING % (type-of "abc") \EV STRING % (type-of "abc") \EV ARRAY %\endcode %If \param{object} is a user-defined named %\term{structure} %created by \macref{defstruct}, then \funref{type-of} %returns the type name %of that \term{structure}. \label Examples:: \code \endcode \issue{TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS} \code (type-of 'a) \EV SYMBOL (type-of '(1 . 2)) \EV CONS \OV (CONS FIXNUM FIXNUM) (type-of #c(0 1)) \EV COMPLEX \OV (COMPLEX INTEGER) (defstruct temp-struct x y z) \EV TEMP-STRUCT (type-of (make-temp-struct)) \EV TEMP-STRUCT (type-of "abc") \EV STRING \OV (STRING 3) (subtypep (type-of "abc") 'string) \EV \term{true}, \term{true} (type-of (expt 2 40)) \EV BIGNUM \OV INTEGER \OV (INTEGER 1099511627776 1099511627776) \OV SYSTEM::TWO-WORD-BIGNUM \OV FIXNUM (subtypep (type-of 112312) 'integer) \EV \term{true}, \term{true} (defvar *foo* (make-array 5 :element-type t)) \EV *FOO* (class-name (class-of *foo*)) \EV VECTOR (type-of *foo*) \EV VECTOR \OV (VECTOR T 5) \endcode \endissue{TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS} \label Affected By:\None. \label Exceptional Situations:\None! \label See Also:: \funref{array-element-type}, \funref{class-of}, \macref{defstruct}, \macref{typecase}, \funref{typep}, {\secref\Types} \label Notes:: Implementors are encouraged to arrange for \funref{type-of} to return \issue{TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS} %the most specific \term{type} that can be conveniently computed and %is likely to be useful to the user. a portable value. %Barmar: "a type specifier defined in this standard" %KMP: This is a little messy. The problem is that user-defined types are % not directly described here,... \endissue{TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS} \endcom %%% ========== TYPEP \begincom{typep}\ftype{Function} \issue{SUBTYPEP-ENVIRONMENT:ADD-ARG} \label Syntax:: \DefunWithValues typep {object type-specifier {\opt} environment} {generalized-boolean} \label Arguments and Values:: \param{object}---an \term{object}. \param{type-specifier}---any \term{type specifier} except \issue{FUNCTION-TYPE}% % The following will be deleted from the standard: % % \declref{function}, \endissue{FUNCTION-TYPE}% \misc{values}, or a \term{type specifier} list whose first element is either \misc{function} or \misc{values}. \param{environment}---an \term{environment} \term{object}. \Default{\nil, denoting the \term{null lexical environment} and the and current \term{global environment}} %!!! Need to say what happens with the environment. \param{generalized-boolean}---a \term{generalized boolean}. \label Description:: %% 6.2.1 2 \Predicate{object}{of the \term{type} specified by \param{type-specifier}} % already stated elsewhere, not crucial here. --sjl 7 Mar 92 %\param{Object} can be of more than one \term{type}, %since one \term{type} can include another. A \param{type-specifier} of the form \f{(satisfies fn)} is handled by applying the function \f{fn} to \param{object}. \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} \f{(typep \param{object} '(array \param{type-specifier}))}, where \param{type-specifier} is not \f{*}, returns \term{true} if and only if \param{object} is an \term{array} that could be the result of supplying \param{type-specifier} as the \kwd{element-type} argument to \funref{make-array}. \f{(array *)} refers to all \term{arrays} regardless of element type, while \f{(array \param{type-specifier})} refers only to those \term{arrays} that can result from giving \param{type-specifier} as the \kwd{element-type} argument to \funref{make-array}. A similar interpretation applies to \f{(simple-array \param{type-specifier})} and \f{(vector \param{type-specifier})}. \Seesection\ArrayUpgrading. \f{(typep \param{object} '(complex \param{type-specifier}))} returns \term{true} for all \term{complex} numbers that can result from giving \term{numbers} of type \param{type-specifier} to \thefunction{complex}, plus all other \term{complex} numbers of the same specialized representation. Both the real and the imaginary parts of any such \term{complex} number must satisfy: \code (typep realpart 'type-specifier) (typep imagpart 'type-specifier) \endcode \Seefun{upgraded-complex-part-type}. \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} \label Examples:: \code (typep 12 'integer) \EV \term{true} (typep (1+ most-positive-fixnum) 'fixnum) \EV \term{false} (typep nil t) \EV \term{true} (typep nil nil) \EV \term{false} (typep 1 '(mod 2)) \EV \term{true} (typep #c(1 1) '(complex (eql 1))) \EV \term{true} ;; To understand this next example, you might need to refer to ;; \secref\RuleOfCanonRepForComplexRationals. (typep #c(0 0) '(complex (eql 0))) \EV \term{false} \endcode \issue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} Let \f{A\sssx} and \f{A\sssy} be two \term{type specifiers} that denote different \term{types}, but for which \code (upgraded-array-element-type 'A\sssx) \endcode and \code (upgraded-array-element-type 'A\sssy) \endcode denote the same \term{type}. Notice that \code (typep (make-array 0 :element-type 'A\sssx) '(array A\sssx)) \EV \term{true} (typep (make-array 0 :element-type 'A\sssy) '(array A\sssy)) \EV \term{true} (typep (make-array 0 :element-type 'A\sssx) '(array A\sssy)) \EV \term{true} (typep (make-array 0 :element-type 'A\sssy) '(array A\sssx)) \EV \term{true} \endcode \endissue{ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING} \label Affected By:\None. \label Exceptional Situations:: %% 4.5.0.0 10 An error \oftype{error} is signaled if \param{type-specifier} is \f{values}, or a \term{type specifier} list whose first element is either \misc{function} or \misc{values}. The consequences are undefined if the \param{type-specifier} is not a \term{type specifier}. \label See Also:: \funref{type-of}, \funref{upgraded-array-element-type}, \funref{upgraded-complex-part-type}, {\secref\TypeSpecifiers} \label Notes:: \term{Implementations} are encouraged to recognize and optimize the case of \f{(typep \param{x} (the class \param{y}))}, since it does not involve any need for expansion of \macref{deftype} information at runtime. \code \endcode \endissue{SUBTYPEP-ENVIRONMENT:ADD-ARG} \endcom %-------------------- Type Errors -------------------- \begincom{type-error}\ftype{Condition Type} \label Class Precedence List:: \typeref{type-error}, \typeref{error}, \typeref{serious-condition}, \typeref{condition}, \typeref{t} \label Description:: \Thetype{type-error} represents a situation in which an \term{object} is not of the expected type. The ``offending datum'' and ``expected type'' are initialized by \theinitkeyargs{datum} and \kwd{expected-type} to \funref{make-condition}, and are \term{accessed} by the functions \funref{type-error-datum} and \funref{type-error-expected-type}. \label See Also:: \funref{type-error-datum}, \funref{type-error-expected-type} \endcom%{type-error}\ftype{Condition Type} %%% ========== TYPE-ERROR-DATUM \begincom{type-error-datum, type-error-expected-type}\ftype{Function} \label Syntax:: \DefunWithValues type-error-datum {condition} {datum} \DefunWithValues type-error-expected-type {condition} {expected-type} \label Arguments and Values:: \param{condition}---a \term{condition} \oftype{type-error}. \param{datum}---an \term{object}. \param{expected-type}---a \term{type specifier}. \label Description:: \funref{type-error-datum} returns the offending datum in the \term{situation} represented by the \param{condition}. \funref{type-error-expected-type} returns the expected type of the offending datum in the \term{situation} represented by the \param{condition}. \label Examples:: \code (defun fix-digits (condition) (check-type condition type-error) (let* ((digits '(zero one two three four five six seven eight nine)) (val (position (type-error-datum condition) digits))) (if (and val (subtypep 'fixnum (type-error-expected-type condition))) (store-value 7)))) (defun foo (x) (handler-bind ((type-error #'fix-digits)) (check-type x number) (+ x 3))) (foo 'seven) \EV 10 \endcode \label Side Effects:\None. \label Affected By:\None. \label Exceptional Situations:\None. \label See Also:: \typeref{type-error}, {\secref\Conditions} \label Notes:\None. %% Shouldn't be needed. -kmp 1-Sep-91 %It is an error to use \macref{setf} with \funref{type-error-datum}. %It is an error to use \macref{setf} with \funref{type-error-expected-type}. \endcom %%% ========== SIMPLE-TYPE-ERROR \begincom{simple-type-error}\ftype{Condition Type} \label Class Precedence List:: \issue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \typeref{simple-type-error}, \typeref{simple-condition}, \typeref{type-error}, \typeref{error}, \typeref{serious-condition}, \typeref{condition}, \typeref{t} \endissue{TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND} \label Description:: \term{Conditions} \oftype{simple-type-error} are like \term{conditions} \oftype{type-error}, except that they provide an alternate mechanism for specifying how the \term{condition} is to be \term{reported}; \seetype{simple-condition}. \label See Also:: \typeref{simple-condition}, \issue{FORMAT-STRING-ARGUMENTS:SPECIFY} \funref{simple-condition-format-control}, \endissue{FORMAT-STRING-ARGUMENTS:SPECIFY} \funref{simple-condition-format-arguments}, \funref{type-error-datum}, \funref{type-error-expected-type} \endcom%{simple-type-error}\ftype{Condition Type}