normalize-type

Arguments: type &key loud msg default environment

Returns the normalized form of type, which should be a type specifier. If environment is provided, then it is consulted for possible type information.

Types are normalized by attempting to find the simplest type specification which fully describes all types of similar specification. Sometimes this means that the normalization is itself simpler, but sometimes it results in a slightly larger specification. So, for example, when type is given fixnum, it returns the same thing that evaluating `(integer ,most-negative-fixnum ,most-positive-fixnum) would return. Another example is a combination of (or fixnum bignum). When given that form as an argument, normalize-type returns (integer * *), because fixnums and bignums are an exhaustive subset of the type integer.

Arrays are normalized into their (<array> <etype> <dim>) form, where <array> might be array, simple-array, or excl:short-simple-array, and <etype> is the upgraded array element-type, and <dim> forms the dimensions specifications. If the rank of the array type is unknown, * will be used, otherwise a parenthesized form is always given, with * used in individual dimensions that are unkown.

Thus, (normalize-type '(vector float)) returns the type (array (float * *) (*)) and (normalize-type '(simple-bit-vector 10)) returns (simple-array (integer 0 1) (10)).

If the type argument does not represent a type at the time of the call, the actions of normalize-type are thus:

• With no values specified for loud or default, t is returned.
• If value is specified for default, it is returned.
• If loud is non-nil, then it must be a function-spec or a function object which will be funcalled in the following way:

  (funcall loud msg type)
  

  and if this function returns, then normalize-type will return the default. This allows several styles to be employed, and the most common style is for msg to be a format string which accepts one argument, and loud can either be warn, error, or cerror, though in fact loud and msg can be used in other ways, as well.

If the type argument is a malformed or impossible type, then loud is called (as described above) if specified and the result is returned, and if loud is not specified, nil is returned.

The msg argument is used only as the first argument to the function which is the value of loud.

Type specifications returned by normalize-type should be considered immutable, and thus should not be destructively modified.

Examples

We make a distinction above between a `malformed or impossible' type, where nil is returned (absent values specified for default and/or loud) and a value for type that `does not represent a type at the time of the call'. The following examples should make this distinction clear.

;;  Consider the following type specifications and assume they are
;;  passed as the TYPE argument:

'foo

;;  If foo hasn't been defined yet, it is an invalid type (though it
;;  might become valid at some other time).  NORMALIZE-TYPE returns T, 
;;  or calls the LOUD function.

'(array foo)

;;  If foo isn't defined, then it is not known whether it will eventually
;;  represent a T or some specialized element-type - in this case
;;  NORMALIZE-TYPE recursively calls itself with a default of '*.  Back
;;  at the other call, if LOUD is specified, it is called, otherwise
;;  (ARRAY * *) is returned.

'(array foo bar bas)

;;  This can never be a type, because it is malformed.  Either LOUD is
;;  called or NIL is returned.

'(and fixnum bignum)

;; This one might seem like an impossible type, but it is not.
;; Since there are no values that are both a fixnum and a bignum, 
;; the result type is NIL, which means the empty type, and 
;; LOUD is never called even if specified.

'(mod -2)

;; This is an impossible type The MOD value must be positive).
;; Either LOUD is called, or NIL is returned.

Copyright (c) 1998-2015, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 10.0. This page was not revised from the 9.0 page.
Created 2015.5.21.