ToC DocOverview CGDoc RelNotes Index PermutedIndex
Allegro CL
Home Previous Up Next Table of Contents Index
  ANSI Common Lisp   4 Types and Classes   4.4 Dictionary of Types and Classes

4.4.24 coerce Function

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:

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))

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

Allegro CL Implementation Details:
None.

Home Previous Up Next Table of Contents Index
© Franz Inc. All Rights Reserved - File last updated 2022-07-25