**Syntax:**

**coerce** *object result-type* => *result*

**Arguments and Values:**

*object*---an *object*.

*result-type*---a *type specifier*.

*result*---an *object*, of *type* *result-type* except in situations described in Section 12.1.5.3 (Rule of Canonical Representation for Complex Rationals).

**Description:**

*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:

**sequence**-
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. **character**-
If the
*result-type*is**character**and the*object*is a*character designator*, the*result*is the*character*it denotes. **complex**-
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 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
*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*.) **function**-
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*. **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 'short-float) => 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) '(simple-bit-vector 3))

**Affected By:** None.

**Exceptional Situations:**

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.

**See Also:**

**rational**, **floor**, **char-code**, **char-int**

**Notes:**

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

(coerce x 't) == (identity x) == x

The following X3J13 cleanup issues,

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