**coerce***object result-type*→*result*

*object*- an*object*.*result-type*- a*type specifier*.

*Coerces* the *object* to *type* *result-type*.

If *object* is already of *type* *result-type*, the *object* itself is returned, regardless of whether it would have been possible in general to coerce an *object* of some other *type* to *result-type*.

Otherwise, the *object* is *coerced* to *type* *result-type* according to the following rules:

If the *result-type* 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 *result-type* 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 *result-type* 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.

If the *result-type* is **character** and the *object* is a *character designator*, the *result* is the *character* it denotes.

If the *result-type* 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 {\secref\RuleOfCanonRepForComplexRationals}. So, for example, `(coerce 3 'complex)`

is permissible, but will return `3`

, which is not a *complex*.)

If the *result-type* is any of **float**, **short-float**, **single-float**, **double-float**, **long-float**,and the *object* is a *real*, then the *result* is a *float* of *type* *result-type* which is equal in sign and magnitude to the *object* to whatever degree of representational precision is permitted by that *float* representation. (If the *result-type* is **float** and *object* is not already a *float*, then the *result* is a *single float*.)

If the *result-type* 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 *result-type* is **function**,and *object* is a *lambda expression*, then the *result* is a *closure* of *object* in the *null lexical environment*.

(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 'short-float)

→0.0s0

(coerce 3.5L0 'float)

→3.5L0

(coerce 7/2 'float)

→3.5

→(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) '(simple-bit-vector 3))

None.

If a coercion is not possible, an error of type **type-error** is signaled.

`(coerce x 'nil)`

always signals an error of type **type-error**.

An error of type **error** is signaled if the *result-type* 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 **type-error** should be signaled if *result-type* specifies the number of elements and *object* is of a different length.

Coercions from *floats* to *rationals* and from *ratios* to *integers* are not provided because of rounding problems.

\issue{FUNCTION-TYPE:X3J13-MARCH-88} \issue{COERCING-SETF-NAME-TO-FUNCTION:ALL-FUNCTION-NAMES} \issue{SEQUENCE-TYPE-LENGTH:MUST-MATCH} \issue{SEQUENCE-TYPE-LENGTH:MUST-MATCH} \issue{CONCATENATE-SEQUENCE:SIGNAL-ERROR} \issue{CHARACTER-LOOSE-ENDS:FIX} \issue{REAL-NUMBER-TYPE:X3J13-MAR-89}