4.8. Type Conversion Function

The following function may be used to convert an object to an equivalent object of another type.

[Function]
coerce object result-type

The result-type must be a type specifier; the object is converted to an ``equivalent'' object of the specified type. If the coercion cannot be performed then an error is signaled. In particular (coerce x 'nil) always signals an error. If object is already of the specified type as determined by typep then it is simply returned. It is not generally possible to convert any object to be of any type whatsoever; only certain conversions are permitted:

Any sequence type may be converted to any other sequence type provided the new sequence can contain all actual elements of the old sequence (it is an error if it cannot). If the result-type is specified as simply array for example then (array t) is assumed. A specialized type such as string or (vector (complex short-float)) may be specified; of course the result may be of either that type or some more general type as determined by the implementation. Elements of the new sequence will be eql to corresponding elements of the old sequence. If the sequence is already of the specified type it may be returned without copying it; in this (coerce sequence type) differs from (concatenate type sequence) for the latter is required to copy the argument sequence. In particular if one specifies sequence then the argument may simply be returned if it already is a sequence.
```
(coerce '(a b c) 'vector) => #(a b c)
```

change_begin
X3J13 voted in June 1989 (SEQUENCE-TYPE-LENGTH) to specify that coerce should signal an error if the new sequence type specifies the number of elements and the old sequence has a different length.

X3J13 voted in March 1989 (CHARACTER-PROPOSAL) to specify that if the result-type is string then it is understood to mean (vector character) then it is understood to mean (vector character)tt> es thepecify that/next_motif.gif">