Skip to main content

upgraded-array-element-type

upgraded-array-element-type Function

Syntax:

upgraded-array-element-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 current global environment.

upgraded-typespec—a type specifier .

Description:

Returns the element type of the most specialized array representation capable of holding items of the type denoted by typespec.

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

If typespec is bit, the result is type equivalent to bit. If typespec is base-char, the result is type equivalent to base-char. If typespec is character, the result is type equivalent to character.

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

The environment is used to expand any derived type specifiers that are mentioned in the typespec.

See Also:

array-element-type, make-array

Notes:

Except for storage allocation consequences and dealing correctly with the optional environment argument, upgraded-array-element-type could be defined as:

(defun upgraded-array-element-type (type &optional environment)

(array-element-type (make-array 0 :element-type type)))

Expanded Reference: upgraded-array-element-type​

Basic Usage​

upgraded-array-element-type returns the element type that the implementation would actually use for an array requested with the given type specifier. This reveals the implementation's type upgrading behavior.

;; T is always upgraded to T
(upgraded-array-element-type 't)
=> T

;; BIT always upgrades to BIT
(upgraded-array-element-type 'bit)
=> BIT

;; CHARACTER upgrades to CHARACTER (or BASE-CHAR)
(upgraded-array-element-type 'character)
=> CHARACTER

Understanding Type Upgrading​

Implementations often have a limited set of specialized array representations. Requested types are "upgraded" to the nearest available type.

;; Requesting (unsigned-byte 4) might upgrade to (unsigned-byte 8) or wider
(let ((upgraded (upgraded-array-element-type '(unsigned-byte 4))))
  (subtypep '(unsigned-byte 4) upgraded))
=> T
=> T

;; Requesting (unsigned-byte 8) -- common specialization
(upgraded-array-element-type '(unsigned-byte 8))
=> (UNSIGNED-BYTE 8)

Relationship to array-element-type​

upgraded-array-element-type tells you what type an array would have; array-element-type tells you what type an existing array does have.

(let ((a (make-array 4 :element-type 'bit)))
  (equal (upgraded-array-element-type 'bit)
         (array-element-type a)))
=> T

Practical Use: Checking Specialization Support​

You can use this function to check if the implementation provides specialized storage for a given type.

;; Check if single-float arrays are specialized
(let ((upgraded (upgraded-array-element-type 'single-float)))
  (if (eq upgraded t)
      :not-specialized
      :specialized))
=> :SPECIALIZED