coerce

(coerce object result-type)

Converts object to the given sequence, float, complex, real, or function type. result-type may be 'list, 'vector, 'string (and their simple-/base- spellings), a compound spec such as '(vector t) or '(string 8), a float type ('float, 'single-float, 'double-float, 'short-float, 'long-float -- all the one double representation), 'complex (a complex answers itself; a real answers complex of itself, demoted when exact, so (coerce 5 'complex) is 5 and (coerce 5.0 'complex) is #C(5.0 0.0)), '(complex part-type) (both parts are coerced first, so (coerce 5 '(complex single-float)) is #C(5.0 0.0)), 'real (a real answers itself; anything else signals a catchable type error), 'function (a function is returned as is, a symbol resolves through symbol-function, and a literal lambda list becomes the closure), or t (the identity). A COMPUTED result type is accepted too and dispatches at runtime over exactly those families, so an expression like (coerce seq type) with type in a variable behaves the same as the literal form; a zero-parameter deftype name resolves to what it expands to first. A 'string result requires a sequence of characters, and a value already of the requested type is returned unchanged -- for a 'simple-string result that means a SIMPLE string only, so a fill-pointered or adjustable character vector is rebuilt rather than handed back. #'coerce is a function value too, with the same computed-type dispatch.

A vector result-type spelling an (unsigned-byte 8), (unsigned-byte 16) or (unsigned-byte 32) element type -- '(vector (unsigned-byte 8)), '(simple-array (unsigned-byte 32) (*)) -- builds a specialized vector of that element type, the same representation make-array and concatenate produce, so array-element-type reports it and typep against the matching simple-array specifier answers true. Elements are stored masked to the element width. Any other element type builds a general vector, whose element type is t. This is the spelling a lookup table usually takes, and a table whose elements are all literals is built at compile time on the compiled backends.

A vector result-type spelling one of the packed float element types -- '(vector single-float), '(simple-array double-float (*)), '(array bfloat16) -- builds a packed float array of that width, the same representation make-array produces, so array-element-type reports it back. Elements are stored at the array's own width, so an integer element becomes a float and a wider one is narrowed; a non-real element is an error. bfloat16 arrays exist on the interpreter and the JVM backend only.

A vector result-type spelling character -- '(vector character) -- builds a string instead, the same representation make-array's :element-type 'character produces: array-element-type answers character, stringp is true, and the printed form is a normal string.