Skip to main content

upgraded-complex-part-type

upgraded-complex-part-type Function

Syntax:

upgraded-complex-part-type typespec &optional environment → upgraded-typespec

Arguments and Values:

typespec—a type specifier .

environment—an environment object. The default is nil, denoting the null lexical environment and the and current global environment.

upgraded-typespec—a type specifier .

Description:

upgraded-complex-part-type returns the part type of the most specialized complex number representation that can hold parts of type typespec.

The typespec is a subtype of (and possibly type equivalent to) the upgraded-typespec.

The purpose of upgraded-complex-part-type is to reveal how an implementation does its upgrading.

See Also:

complex (function and type)

Notes:

Expanded Reference: upgraded-complex-part-type​

Basic Usage​

The function upgraded-complex-part-type returns the type to which the implementation upgrades the parts of a complex number when given a specified part type. This is analogous to upgraded-array-element-type for arrays.

(upgraded-complex-part-type 'integer)
=> RATIONAL
(upgraded-complex-part-type 'single-float)
=> SINGLE-FLOAT
(upgraded-complex-part-type 'double-float)
=> DOUBLE-FLOAT
(upgraded-complex-part-type 'rational)
=> RATIONAL

Understanding Upgrading​

Implementations may not support complex numbers with arbitrary part types. When you create a complex number, the parts may be upgraded (widened) to a type the implementation actually supports.

;; The actual part type may be wider than requested
(upgraded-complex-part-type '(integer 0 10))
=> RATIONAL

(upgraded-complex-part-type 'bit)
=> RATIONAL

(upgraded-complex-part-type 'real)
=> REAL

Relationship to Complex Type Specifiers​

The upgraded type determines what (complex <type>) actually contains. Two different specified types may upgrade to the same actual type.

;; These may all upgrade to the same internal type
(upgraded-complex-part-type 'fixnum)
=> RATIONAL
(upgraded-complex-part-type 'integer)
=> RATIONAL
(upgraded-complex-part-type 'rational)
=> RATIONAL

;; Creating complex numbers and checking actual types
(type-of (complex 1 2))
=> (COMPLEX RATIONAL)
(type-of (complex 1.0 2.0))
=> (COMPLEX SINGLE-FLOAT)
(type-of (complex 1.0d0 2.0d0))
=> (COMPLEX DOUBLE-FLOAT)

Optional Environment Argument​

The function accepts an optional environment argument for use in macros, though in most practical usage it is omitted.

;; Without environment (most common usage)
(upgraded-complex-part-type 'single-float)
=> SINGLE-FLOAT

;; With nil environment (equivalent to no environment)
(upgraded-complex-part-type 'single-float nil)
=> SINGLE-FLOAT