Function coerce

Syntax:

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:

4.8.0 3Coerces 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.

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

• sequence

  If the \param{result-type} is a \term{subtype} of \typeref{list}, the result will be a \term{list}. If the \param{result-type} is a \term{subtype} of \typeref{vector}, then if the implementation can determine the element type specified for the \param{result-type}, the element type of the resulting array is the result of \term{upgrading} that element type; or, if the implementation can determine that the element type is unspecified (or \f{*}), the element type of the resulting array is \typeref{t}; otherwise, an error is signaled.

  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.

  I don't understand this and I can't figure out where it came from. It's stated below that an error is signaled if the appropriate result cannot be constructed. --sjl 7 Mar 92 The consequences are undefined if the \param{result} is not of \term{type} \param{result-type}.

• character

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

  Reference to INT-CHAR removed.

• complex

  4.8.0 7If the result-type is complex "number" => "real" per Boyer/Kaufmann/Moore #7 (by X3J13 vote at May 4-5, 1994 meeting) -kmp 9-May-94and 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

  4.8.0 6If 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 Barmar asked what about (COERCE '(SETF symbol) 'FUNCTION) Mail sent to Quinquevirate. -kmp 3-Jun-91 This change was the result of that discussion. kmp 14-May-93 \term{symbol}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

  4.8.0 8Any 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 KMP: I'm not sure UNDEFINED-FUNCTION is the right error type to signal here. Barrett: Yeah. This isn't really right for `fbound but not function'. Make it ERROR. KMP: Doneof 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:

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

 (coerce x 't) ≡ (identity x) ≡ x