9.3 Type Declaration for Forms

Frequently it is useful to declare that the value produced by the evaluation of some form will be of a particular type. Using declare one can declare the type of the value held by a bound variable, but there is no easy way to declare the type of the value of an unnamed form. For this purpose the the special operator is defined; (the type form) means that the value of form is declared to be of type type.

[Special operator] the value-type form

The form is evaluated; whatever it produces is returned by the the form. In addition, it is an error if what is produced by the form does not conform to the data type specified by value-type (which is not evaluated). (A given implementation may or may not actually check for this error. Implementations are encouraged to make an explicit error check when running interpretively.) In effect, this declares that the user undertakes to guarantee that the values of the form will always be of the specified type. For example:

(the string (copy-seq x))     ;The result will be a string
(the integer (+ x 3))         ;The result of + will be an integer
(+ (the integer x) 3)         ;The value of x will be an integer
(the (complex rational) (* z 3))
(the (unsigned-byte 8) (logand x mask))

The values type specifier may be used to indicate the types of multiple values:

(the (values integer integer) (floor x y))
(the (values string t)
     (gethash the-key the-string-table))

value-type may be any valid type specifier whatsoever. The point is that a type specifier need not be one suitable for discrimination but only for declaration.

In the case that the form produces exactly one value and value-type is not a values type specifier, one may describe a the form as being entirely equivalent to

(let ((#1=#:temp form)) (declare (type value-type #1#)) #1#)

A more elaborate expression could be written to describe the case where value-type is a values type specifier.