
ANSI Common Lisp 4 Types and Classes 4.4 Dictionary of Types and Classes
 Syntax:

coerce
object resulttype
result
 Arguments and Values:

object  an object.
resulttype  a type specifier.
result  an object, of type resulttype
except in situations described in Section 12.1.5.3 Rule of Canonical Representation for Complex Rationals.
 Description:

Coerces the object to type resulttype.
If object is already of type resulttype,
the object itself is returned, regardless of whether it
would have been possible in general to coerce an object of
some other type to resulttype.
Otherwise, the object is coerced to type resulttype
according to the following rules:
 sequence
If the resulttype is a recognizable subtype of list,
and the object is a sequence,
then the result is a list
that has the same elements as object.
If the resulttype is a recognizable subtype of vector,
and the object is a sequence,
then the result is a vector
that has the same elements as object.
If resulttype is a specialized type,
the result has an actual array element type that is the result of
upgrading the element type part of that specialized type.
If no element type is specified, the element type defaults to t.
If the implementation cannot determine the element type, an error is signaled.
 character
If the resulttype is character
and the object is a character designator,
the result is the character it denotes.
 complex
If the resulttype is complex
and the object is a real,
then the result is obtained by constructing a complex
whose real part is the object and
whose imaginary part is the result of coercing an integer zero
to the type of the object (using coerce).
(If the real part is a rational, however,
then the result must be represented as a rational rather
than a complex; see Section 12.1.5.3 Rule of Canonical Representation for Complex Rationals.
So, for example, (coerce 3 'complex) is permissible,
but will return 3, which is not a complex.)
 float
If the resulttype is any of float,
shortfloat,
singlefloat,
doublefloat,
longfloat,
and the object is a
real,
then the result is a float of type resulttype
which is equal in sign and magnitude to the object to whatever degree of
representational precision is permitted by that float representation.
(If the resulttype is float
and object is not already a float,
then the result is a single float.)
 function
If the resulttype is function,
and object is any
function name
that is fbound
but that is globally defined neither as a macro name nor as a special operator,
then the result is the functional value of object.
If the resulttype is function,
and object is a lambda expression,
then the result is a closure of object
in the null lexical environment.
 t
Any object can be coerced to an object of type t.
In this case, the object is simply returned.
 Examples:

(coerce '(a b c) 'vector) #(A B C)
(coerce 'a 'character) #\A
(coerce 4.56 'complex) #C(4.56 0.0)
(coerce 4.5s0 'complex) #C(4.5s0 0.0s0)
(coerce 7/2 'complex) 7/2
(coerce 0 'shortfloat) 0.0s0
(coerce 3.5L0 'float) 3.5L0
(coerce 7/2 'float) 3.5
(coerce (cons 1 2) t) (1 . 2)
All the following forms should signal an error:
(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) '(simplebitvector 3))
 Exceptional Situations:

If a coercion is not possible, an error of type typeerror is signaled.
(coerce x 'nil) always signals an error of type typeerror.
An error
of type error is signaled
if the resulttype is function but
object is a symbol that is not fbound or
if the symbol names a macro or a special operator.
An error of type typeerror should be signaled if resulttype
specifies the number of elements and object is of a different length.
 See Also:

rational, floor, charcode, charint
 Notes:

Coercions from floats to rationals
and from ratios to integers
are not provided because of rounding problems.
(coerce x 't) ==(identity x) == x
 Allegro CL Implementation Details:

None.
