diff --git a/spec/draft/API_specification/data_types.rst b/spec/draft/API_specification/data_types.rst index a9be88181..5987dd322 100644 --- a/spec/draft/API_specification/data_types.rst +++ b/spec/draft/API_specification/data_types.rst @@ -5,109 +5,83 @@ Data Types Array API specification for supported data types. -A conforming implementation of the array API standard must provide and support the following data types. +A conforming implementation of the array API standard must provide and support +the following data types ("dtypes") in its array object, and as data type +objects in its main namespace under the specified names: + ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| dtype object | description | ++==============+============================================================================================================================================================================================+ +| bool | Boolean (``True`` or ``False``). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| complex64 | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| complex128 | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Data type objects must have the following methods (no attributes are required): -bool ----- - -Boolean (``True`` or ``False``). - -int8 ----- - -An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. - -int16 ------ - -A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. - -int32 ------ - -A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. - -int64 ------ - -A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. - -uint8 ------ - -An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. - -uint16 ------- - -A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. - -uint32 ------- - -A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. - -uint64 ------- - -A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. - -float32 -------- - -IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). - -float64 -------- +.. + NOTE: please keep the functions in alphabetical order -IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). +.. currentmodule:: array_api.data_types -complex64 ---------- +.. autosummary:: + :toctree: generated + :template: method.rst -Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). + __eq__ -complex128 ----------- -Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). +.. note:: + A conforming implementation of the array API standard may provide and + support additional data types beyond those described in this specification. + It may also support additional methods and attributes on dtype objects. .. note:: IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks. Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers. -.. note:: - A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification. - -.. _data-type-objects: -Data Type Objects ------------------ +Use of data type objects +------------------------ -Data types ("dtypes") are objects which are used as ``dtype`` specifiers in functions and methods (e.g., ``zeros((2, 3), dtype=float32)``). +Data type objects are used as ``dtype`` specifiers in functions and methods +(e.g., ``zeros((2, 3), dtype=float32)``), accessible as ``.dtype`` attribute on +arrays, and used in various casting and introspection functions (e.g., +``isdtype(x.dtype, 'integral')``). -.. note:: - A conforming implementation may add additional methods or attributes to data type objects beyond those described in this specification. +``dtype`` keywords in functions specify the data type of arrays returned from +functions or methods. ``dtype`` keywords are not required to affect the data +type used for intermediate calculations or results (e.g., implementors are free +to use a higher-precision data type when accumulating values for reductions, as +long as the returned array has the specified data type). .. note:: Implementations may provide other ways to specify data types (e.g., ``zeros((2, 3), dtype='f4')``) which are not described in this specification; however, in order to ensure portability, array library consumers are recommended to use data type objects as provided by specification conforming array libraries. -A conforming implementation of the array API standard must provide and support data type objects having the following attributes and methods. - -Methods -~~~~~~~ - -.. - NOTE: please keep the functions in alphabetical order - -.. currentmodule:: array_api.data_types - -.. autosummary:: - :toctree: generated - :template: method.rst - - __eq__ +See :ref:`type-promotion` for specification guidance describing the rules governing the interaction of two or more data types or data type objects. .. _data-type-defaults: @@ -138,6 +112,7 @@ the library should clearly warn about this in its documentation. .. note:: The default data types should be clearly defined in a conforming library's documentation. + .. _data-type-categories: Data Type Categories @@ -145,41 +120,24 @@ Data Type Categories For the purpose of organizing functions within this specification, the following data type categories are defined. -.. note:: - Conforming libraries are not required to organize data types according to these categories. These categories are only intended for use within this specification. - - -Numeric Data Types -~~~~~~~~~~~~~~~~~~ - -``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, ``float64``, ``complex64``, and ``complex128``. - -Real-valued Data Types -~~~~~~~~~~~~~~~~~~~~~~ - -``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, and ``float64``. - -Integer Data Types -~~~~~~~~~~~~~~~~~~ - -``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, and ``uint64``. - -Floating-point Data Types -~~~~~~~~~~~~~~~~~~~~~~~~~ ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data type category | dtypes | ++============================+========================================================================================================================================================+ +| Numeric | ``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, ``float64``, ``complex64``, and ``complex128``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Real-valued | ``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``float32``, and ``float64``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Integer | ``int8``, ``int16``, ``int32``, ``int64``, ``uint8``, ``uint16``, ``uint32``, and ``uint64``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Floating-point | ``float32``, ``float64``, ``complex64``, and ``complex128``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Real-valued floating-point | ``float32`` and ``float64``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Complex floating-point | ``complex64`` and ``complex128``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Boolean | ``bool``. | ++----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -``float32``, ``float64``, ``complex64``, and ``complex128``. -Real-valued Floating-point Data Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``float32`` and ``float64``. - -Complex Floating-point Data Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``complex64`` and ``complex128``. - -Boolean Data Types -~~~~~~~~~~~~~~~~~~ - -``bool``. +.. note:: + Conforming libraries are not required to organize data types according to these categories. These categories are only intended for use within this specification.