Type Promotion Rules¶
Array API specification for type promotion rules.
Type promotion rules can be understood at a high level from the following diagram:
Type promotion diagram. Promotion between any two types is given by their join on this lattice. Only the types of participating arrays matter, not their values. Dashed lines indicate that behavior for Python scalars is undefined on overflow. Boolean, integer and floatingpoint dtypes are not connected, indicating mixedkind promotion is undefined.
Rules¶
A conforming implementation of the array API standard must implement the following type promotion rules governing the common result type for two array operands during an arithmetic operation.
A conforming implementation of the array API standard may support additional type promotion rules beyond those described in this specification.
Note
Type codes are used here to keep tables readable; they are not part of the standard. In code, use the data type objects specified in Data Types (e.g., int16
rather than 'i2'
).
The following type promotion tables specify the casting behavior for operations involving two array operands. When more than two array operands participate, application of the promotion tables is associative (i.e., the result does not depend on operand order).
Signed integer type promotion table¶
i1 
i2 
i4 
i8 


i1 
i1 
i2 
i4 
i8 
i2 
i2 
i2 
i4 
i8 
i4 
i4 
i4 
i4 
i8 
i8 
i8 
i8 
i8 
i8 
where
i1: 8bit signed integer (i.e.,
int8
)i2: 16bit signed integer (i.e.,
int16
)i4: 32bit signed integer (i.e.,
int32
)i8: 64bit signed integer (i.e.,
int64
)
Unsigned integer type promotion table¶
u1 
u2 
u4 
u8 


u1 
u1 
u2 
u4 
u8 
u2 
u2 
u2 
u4 
u8 
u4 
u4 
u4 
u4 
u8 
u8 
u8 
u8 
u8 
u8 
where
u1: 8bit unsigned integer (i.e.,
uint8
)u2: 16bit unsigned integer (i.e.,
uint16
)u4: 32bit unsigned integer (i.e.,
uint32
)u8: 64bit unsigned integer (i.e.,
uint64
)
Mixed unsigned and signed integer type promotion table¶
u1 
u2 
u4 


i1 
i2 
i4 
i8 
i2 
i2 
i4 
i8 
i4 
i4 
i4 
i8 
i8 
i8 
i8 
i8 
Floatingpoint type promotion table¶
f4 
f8 
c8 
c16 


f4 
f4 
f8 
c8 
c16 
f8 
f8 
f8 
c16 
c16 
c8 
c8 
c16 
c8 
c16 
c16 
c16 
c16 
c16 
c16 
where
f4: singleprecision (32bit) floatingpoint number (i.e.,
float32
)f8: doubleprecision (64bit) floatingpoint number (i.e.,
float64
)c8: singleprecision complex floatingpoint number (i.e.,
complex64
) composed of two singleprecision (32bit) floatingpoint numbersc16: doubleprecision complex floatingpoint number (i.e.,
complex128
) composed of two doubleprecision (64bit) floatingpoint numbers
Notes¶
Type promotion rules must apply when determining the common result type for two array operands during an arithmetic operation, regardless of array dimension. Accordingly, zerodimensional arrays must be subject to the same type promotion rules as dimensional arrays.
Type promotion of nonnumerical data types to numerical data types is unspecified (e.g.,
bool
tointxx
orfloatxx
).
Note
Mixed integer and floatingpoint type promotion rules are not specified because behavior varies between implementations.
Mixing arrays with Python scalars¶
Using Python scalars (i.e., instances of bool
, int
, float
, complex
) together with arrays must be supported for:
array <op> scalar
scalar <op> array
where <op>
is a builtin operator (including inplace operators, but excluding the matmul @
operator; see Operators for operators supported by the array object) and scalar
has a type and value compatible with the array data type:
a Python
bool
for abool
array data type.a Python
int
within the bounds of the given data type for integer array Data Types.a Python
int
orfloat
for realvalued floatingpoint array data types.a Python
int
,float
, orcomplex
for complex floatingpoint array data types.
Provided the above requirements are met, the expected behavior is equivalent to:
Convert the scalar to zerodimensional array with the same data type as that of the array used in the expression.
Execute the operation for
array <op> 0D array
(or0D array <op> array
ifscalar
was the lefthand argument).
Note
Behavior is not specified when mixing a Python float
and an array with an integer data type; this may give float32
, float64
, or raise an exception. Behavior is implementationspecific.
Similarly, behavior is not specified when mixing a Python complex
and an array with a realvalued data type; this may give complex64
, complex128
, or raise an exception. Behavior is implementationspecific.
Behavior is also not specified for integers outside of the bounds of a given integer data type. Integers outside of bounds may result in overflow or an error.