From 2a82758236c73835704d3c8211b463af374f7482 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Thu, 24 Oct 2024 14:17:44 +0000 Subject: [PATCH 01/11] feat: `astype`: accept a kind of data type --- .../_draft/data_type_functions.py | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index e12d349c6..c8d236625 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -16,7 +16,7 @@ def astype( x: array, dtype: dtype, /, *, copy: bool = True, device: Optional[device] = None ) -> array: """ - Copies an array to a specified data type irrespective of :ref:`type-promotion` rules. + Copies an array to a specified data type irrespective of :ref:`type-promotion` rules, or to a *kind* of data type. .. note:: Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. @@ -40,8 +40,14 @@ def astype( ---------- x: array array to cast. - dtype: dtype - desired data type. + dtype_or_kind: Union[dtype, str] + desired data type or kind of data type. Supported kinds are: + - ``'bool'``: boolean data types (e.g., ``bool``). + - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). + - ``'unsigned integer'``: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``). + - ``'integral'``: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. + - ``'real floating'``: real-valued floating-point data types (e.g., ``float32``, ``float64``). + - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). copy: bool specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``. device: Optional[device] @@ -50,7 +56,15 @@ def astype( Returns ------- out: array - an array having the specified data type. The returned array must have the same shape as ``x``. + For ``dtype_or_kind`` a data type, an array having the specified data type. + For ``dtype_or_kind`` a kind of data type: + - If ``x.dtype`` is already of that kind, the data type is maintained. + - Otherwise, an attempt is made to convert to the specified kind, according to the type promotion rules (see :ref:`type-promotion`). + - Numeric kinds are interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. + For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, + since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. + - For kind ``integral``, the 'lowest-precision standard data type' is interpreted as ``int8``, not ``uint8``. + The returned array must have the same shape as ``x``. Notes ----- From 419041b83364897ff0ed26dac2a575af037650e2 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Thu, 24 Oct 2024 14:24:48 +0000 Subject: [PATCH 02/11] try to fix docs build --- src/array_api_stubs/_draft/data_type_functions.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index c8d236625..6c62e8d9f 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -58,12 +58,12 @@ def astype( out: array For ``dtype_or_kind`` a data type, an array having the specified data type. For ``dtype_or_kind`` a kind of data type: - - If ``x.dtype`` is already of that kind, the data type is maintained. - - Otherwise, an attempt is made to convert to the specified kind, according to the type promotion rules (see :ref:`type-promotion`). - - Numeric kinds are interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. - For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, - since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. - - For kind ``integral``, the 'lowest-precision standard data type' is interpreted as ``int8``, not ``uint8``. + - If ``x.dtype`` is already of that kind, the data type is maintained. + - Otherwise, an attempt is made to convert to the specified kind, according to the type promotion rules (see :ref:`type-promotion`). + + - Numeric kinds are interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. + - For kind ``integral``, the 'lowest-precision standard data type' is interpreted as ``int8``, not ``uint8``. + The returned array must have the same shape as ``x``. Notes From 302cf1aa1acf34da5cf165be81731fb92f894966 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Thu, 24 Oct 2024 14:33:16 +0000 Subject: [PATCH 03/11] change signature --- src/array_api_stubs/_draft/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 6c62e8d9f..c40f8db00 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -13,7 +13,7 @@ def astype( - x: array, dtype: dtype, /, *, copy: bool = True, device: Optional[device] = None + x: array, dtype_or_kind: Union[dtype, str], /, *, copy: bool = True, device: Optional[device] = None ) -> array: """ Copies an array to a specified data type irrespective of :ref:`type-promotion` rules, or to a *kind* of data type. From 3186995b61049cc2907914417777f08e8753c940 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Thu, 24 Oct 2024 14:43:59 +0000 Subject: [PATCH 04/11] run pre-commit --- src/array_api_stubs/_draft/data_type_functions.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index c40f8db00..8e6817fa0 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -13,7 +13,12 @@ def astype( - x: array, dtype_or_kind: Union[dtype, str], /, *, copy: bool = True, device: Optional[device] = None + x: array, + dtype_or_kind: Union[dtype, str], + /, + *, + copy: bool = True, + device: Optional[device] = None, ) -> array: """ Copies an array to a specified data type irrespective of :ref:`type-promotion` rules, or to a *kind* of data type. From 90aa7504da27cb909406b8977ad974b0ca2d00c5 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sun, 27 Oct 2024 16:20:20 +0000 Subject: [PATCH 05/11] address review comments --- src/array_api_stubs/_draft/data_type_functions.py | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 8e6817fa0..3374462b6 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -14,7 +14,7 @@ def astype( x: array, - dtype_or_kind: Union[dtype, str], + dtype: Union[dtype, str], /, *, copy: bool = True, @@ -45,13 +45,9 @@ def astype( ---------- x: array array to cast. - dtype_or_kind: Union[dtype, str] + dtype: Union[dtype, str] desired data type or kind of data type. Supported kinds are: - - ``'bool'``: boolean data types (e.g., ``bool``). - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). - - ``'unsigned integer'``: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``). - - ``'integral'``: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. - - ``'real floating'``: real-valued floating-point data types (e.g., ``float32``, ``float64``). - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). copy: bool specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``. @@ -67,7 +63,6 @@ def astype( - Otherwise, an attempt is made to convert to the specified kind, according to the type promotion rules (see :ref:`type-promotion`). - Numeric kinds are interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. - - For kind ``integral``, the 'lowest-precision standard data type' is interpreted as ``int8``, not ``uint8``. The returned array must have the same shape as ``x``. From 41880c096c1aaedff9f47a207cd6b67501ee1f9e Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Mon, 28 Oct 2024 12:05:37 +0000 Subject: [PATCH 06/11] adjust wording --- src/array_api_stubs/_draft/data_type_functions.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 3374462b6..a4ca9c2ec 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -57,12 +57,12 @@ def astype( Returns ------- out: array - For ``dtype_or_kind`` a data type, an array having the specified data type. - For ``dtype_or_kind`` a kind of data type: - - If ``x.dtype`` is already of that kind, the data type is maintained. - - Otherwise, an attempt is made to convert to the specified kind, according to the type promotion rules (see :ref:`type-promotion`). + For ``dtype`` a data type, an array having the specified data type. + For ``dtype`` a kind of data type: + - If ``x.dtype`` is already of that kind, the data type must be maintained. + - Otherwise, ``x`` should be cast to a data type of that kind, according to the type promotion rules (see :ref:`type-promotion`) and the above notes. - - Numeric kinds are interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. + - Kinds must be interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. The returned array must have the same shape as ``x``. From d4450b3a0a10c8dbaa20877adb53f72fef8bed78 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Mon, 28 Oct 2024 12:08:15 +0000 Subject: [PATCH 07/11] add note on unspecified promotion --- src/array_api_stubs/_draft/data_type_functions.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index a4ca9c2ec..1ae77abb7 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -63,6 +63,7 @@ def astype( - Otherwise, ``x`` should be cast to a data type of that kind, according to the type promotion rules (see :ref:`type-promotion`) and the above notes. - Kinds must be interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. + - Where type promotion is unspecified and thus implementation-specific, the result is also unspecified. For example, ``astype(x, 'complex floating')``, where ``x`` has data type ``int32``. The returned array must have the same shape as ``x``. From 1b056adb373580c1eebac7664da02a67418c2812 Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Mon, 28 Oct 2024 12:14:51 +0000 Subject: [PATCH 08/11] improve formatting --- src/array_api_stubs/_draft/data_type_functions.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 1ae77abb7..ba428b98b 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -47,8 +47,10 @@ def astype( array to cast. dtype: Union[dtype, str] desired data type or kind of data type. Supported kinds are: + - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). + copy: bool specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``. device: Optional[device] @@ -59,11 +61,11 @@ def astype( out: array For ``dtype`` a data type, an array having the specified data type. For ``dtype`` a kind of data type: + - If ``x.dtype`` is already of that kind, the data type must be maintained. - Otherwise, ``x`` should be cast to a data type of that kind, according to the type promotion rules (see :ref:`type-promotion`) and the above notes. - - - Kinds must be interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. - - Where type promotion is unspecified and thus implementation-specific, the result is also unspecified. For example, ``astype(x, 'complex floating')``, where ``x`` has data type ``int32``. + - Kinds must be interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. + - Where type promotion is unspecified and thus implementation-specific, the result is also unspecified. For example, ``astype(x, 'complex floating')``, where ``x`` has data type ``int32``. The returned array must have the same shape as ``x``. From 169ea5e9ce53122251383b9efd34974b57b0289c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 23 Jan 2025 00:10:26 -0800 Subject: [PATCH 09/11] refactor: update guidance to generalize across data type kinds --- .../_draft/data_type_functions.py | 67 ++++++++++--------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index ba428b98b..38fbf9afc 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -21,35 +21,34 @@ def astype( device: Optional[device] = None, ) -> array: """ - Copies an array to a specified data type irrespective of :ref:`type-promotion` rules, or to a *kind* of data type. - - .. note:: - Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. - - .. note:: - Casting a complex floating-point array to a real-valued data type should not be permitted. - - Historically, when casting a complex floating-point array to a real-valued data type, libraries such as NumPy have discarded imaginary components such that, for a complex floating-point array ``x``, ``astype(x)`` equals ``astype(real(x))``). This behavior is considered problematic as the choice to discard the imaginary component is arbitrary and introduces more than one way to achieve the same outcome (i.e., for a complex floating-point array ``x``, ``astype(x)`` and ``astype(real(x))`` versus only ``astype(imag(x))``). Instead, in order to avoid ambiguity and to promote clarity, this specification requires that array API consumers explicitly express which component should be cast to a specified real-valued data type. - - .. note:: - When casting a boolean input array to a real-valued data type, a value of ``True`` must cast to a real-valued number equal to ``1``, and a value of ``False`` must cast to a real-valued number equal to ``0``. - - When casting a boolean input array to a complex floating-point data type, a value of ``True`` must cast to a complex number equal to ``1 + 0j``, and a value of ``False`` must cast to a complex number equal to ``0 + 0j``. - - .. note:: - When casting a real-valued input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. - - When casting a complex floating-point array to ``bool``, a value of ``0 + 0j`` must cast to ``False``, and all other values must cast to ``True``. + Copies an array to a specified data type or data type kind irrespective of :ref:`type-promotion` rules. Parameters ---------- x: array array to cast. dtype: Union[dtype, str] - desired data type or kind of data type. Supported kinds are: + desired data type or data type kind. + + - If ``dtype`` is a data type, the function must return an array having the specified data type. + - If ``dtype`` is a data type kind, - - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). - - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). + - If the data type of ``x`` belongs to the specified data type kind, the function must return an array having the same data type as ``x``. + - If the data type of ``x`` does not belong to the specified data type kind, the function cast the input array to a data type of the specified data type kind according to type promotion rules (see :ref:`type-promotion`) and the casting rules documented below. + + - When applying type promotion rules, the returned array must have the lowest-precision data type belonging to the specified data type kind to which the data type of ``x`` promotes (e.g., if ``x`` is ``float32`` and the data type kind is ``'complex floating'``, then the returned array must have the data type ``complex64``; if ``x`` is ``uint16`` and the data type kind is ``'signed integer'``, then the returned array must have the data type ``int32``). + - When type promotion rules are not specified between the data type of ``x`` and the specified data type kind (e.g., ``int16`` and ``'real floating'``) and there exists one or more data types belonging to the specified data kind in which the elements in ``x`` can be represented exactly (e.g., ``int32`` and ``float64``), the function must return an array having the smallest data type (in terms of range of values) capable of precisely representing the elements of ``x`` (e.g., if ``x`` is ``int16`` and the data type kind is ``'complex floating'``, then the returned array must have the data type ``complex64``; if ``x`` is `bool`` and the data type kind is ``integral``, then the returned array must have the data type ``int8``). + - When type promotion rules are not specified between the data type of ``x`` and the specified data type kind and there neither exists a data type belonging to the specified data type in which the elements of ``x`` can be represented exactly (e.g., ``uint64`` and ``'real floating'``) nor are there applicable casting rules documented below, behavior is unspecified and thus implementation-defined. + + The following data type kinds must be supported: + + - ``'bool'``: boolean data types (e.g., ``bool``). + - ``'signed integer'``: signed integer data types (e.g., ``int8``, ``int16``, ``int32``, ``int64``). + - ``'unsigned integer'``: unsigned integer data types (e.g., ``uint8``, ``uint16``, ``uint32``, ``uint64``). + - ``'integral'``: integer data types. Shorthand for ``('signed integer', 'unsigned integer')``. + - ``'real floating'``: real-valued floating-point data types (e.g., ``float32``, ``float64``). + - ``'complex floating'``: complex floating-point data types (e.g., ``complex64``, ``complex128``). + - ``'numeric'``: numeric data types. Shorthand for ``('integral', 'real floating', 'complex floating')``. copy: bool specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``. @@ -59,19 +58,25 @@ def astype( Returns ------- out: array - For ``dtype`` a data type, an array having the specified data type. - For ``dtype`` a kind of data type: - - - If ``x.dtype`` is already of that kind, the data type must be maintained. - - Otherwise, ``x`` should be cast to a data type of that kind, according to the type promotion rules (see :ref:`type-promotion`) and the above notes. - - Kinds must be interpreted as the lowest-precision standard data type of that kind for the purposes of type promotion. For example, ``astype(x, 'complex floating')`` will return an array with the data type ``complex64`` when ``x.dtype`` is ``float32``, since ``complex64`` is the result of promoting ``float32`` with the lowest-precision standard complex data type, ``complex64``. - - Where type promotion is unspecified and thus implementation-specific, the result is also unspecified. For example, ``astype(x, 'complex floating')``, where ``x`` has data type ``int32``. - - The returned array must have the same shape as ``x``. + an array having the specified data type or data type kind. The returned array must have the same shape as ``x``. Notes ----- + - Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. + + - Casting a complex floating-point array to a real-valued data type should not be permitted. + + Historically, when casting a complex floating-point array to a real-valued data type, libraries such as NumPy have discarded imaginary components such that, for a complex floating-point array ``x``, ``astype(x)`` equals ``astype(real(x))``). This behavior is considered problematic as the choice to discard the imaginary component is arbitrary and introduces more than one way to achieve the same outcome (i.e., for a complex floating-point array ``x``, ``astype(x)`` and ``astype(real(x))`` versus only ``astype(imag(x))``). Instead, in order to avoid ambiguity and to promote clarity, this specification requires that array API consumers explicitly express which component should be cast to a specified real-valued data type. + + - When casting a boolean input array to a real-valued data type, a value of ``True`` must cast to a real-valued number equal to ``1``, and a value of ``False`` must cast to a real-valued number equal to ``0``. + + - When casting a boolean input array to a complex floating-point data type, a value of ``True`` must cast to a complex number equal to ``1 + 0j``, and a value of ``False`` must cast to a complex number equal to ``0 + 0j``. + + - When casting a real-valued input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. + + - When casting a complex floating-point array to ``bool``, a value of ``0 + 0j`` must cast to ``False``, and all other values must cast to ``True``. + .. versionchanged:: 2022.12 Added complex data type support. From ecd0f5941cfb140656975284bcc094876c788db3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 23 Jan 2025 00:18:22 -0800 Subject: [PATCH 10/11] fix: update copy --- src/array_api_stubs/_draft/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 38fbf9afc..243bff555 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -34,7 +34,7 @@ def astype( - If ``dtype`` is a data type kind, - If the data type of ``x`` belongs to the specified data type kind, the function must return an array having the same data type as ``x``. - - If the data type of ``x`` does not belong to the specified data type kind, the function cast the input array to a data type of the specified data type kind according to type promotion rules (see :ref:`type-promotion`) and the casting rules documented below. + - If the data type of ``x`` does not belong to the specified data type kind, the function must cast the input array to a data type of the specified data type kind according to type promotion rules (see :ref:`type-promotion`) and the casting rules documented below. - When applying type promotion rules, the returned array must have the lowest-precision data type belonging to the specified data type kind to which the data type of ``x`` promotes (e.g., if ``x`` is ``float32`` and the data type kind is ``'complex floating'``, then the returned array must have the data type ``complex64``; if ``x`` is ``uint16`` and the data type kind is ``'signed integer'``, then the returned array must have the data type ``int32``). - When type promotion rules are not specified between the data type of ``x`` and the specified data type kind (e.g., ``int16`` and ``'real floating'``) and there exists one or more data types belonging to the specified data kind in which the elements in ``x`` can be represented exactly (e.g., ``int32`` and ``float64``), the function must return an array having the smallest data type (in terms of range of values) capable of precisely representing the elements of ``x`` (e.g., if ``x`` is ``int16`` and the data type kind is ``'complex floating'``, then the returned array must have the data type ``complex64``; if ``x`` is `bool`` and the data type kind is ``integral``, then the returned array must have the data type ``int8``). From b61122ac899288021b8f8728109f28ec581f1507 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 23 Jan 2025 00:19:14 -0800 Subject: [PATCH 11/11] docs: update copy --- src/array_api_stubs/_draft/data_type_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/data_type_functions.py b/src/array_api_stubs/_draft/data_type_functions.py index 243bff555..c33898955 100644 --- a/src/array_api_stubs/_draft/data_type_functions.py +++ b/src/array_api_stubs/_draft/data_type_functions.py @@ -34,7 +34,7 @@ def astype( - If ``dtype`` is a data type kind, - If the data type of ``x`` belongs to the specified data type kind, the function must return an array having the same data type as ``x``. - - If the data type of ``x`` does not belong to the specified data type kind, the function must cast the input array to a data type of the specified data type kind according to type promotion rules (see :ref:`type-promotion`) and the casting rules documented below. + - If the data type of ``x`` does not belong to the specified data type kind, the function must cast the input array to a data type of the specified data type kind according to type promotion rules (see :ref:`type-promotion`), the casting rules documented below, and the following rules: - When applying type promotion rules, the returned array must have the lowest-precision data type belonging to the specified data type kind to which the data type of ``x`` promotes (e.g., if ``x`` is ``float32`` and the data type kind is ``'complex floating'``, then the returned array must have the data type ``complex64``; if ``x`` is ``uint16`` and the data type kind is ``'signed integer'``, then the returned array must have the data type ``int32``). - When type promotion rules are not specified between the data type of ``x`` and the specified data type kind (e.g., ``int16`` and ``'real floating'``) and there exists one or more data types belonging to the specified data kind in which the elements in ``x`` can be represented exactly (e.g., ``int32`` and ``float64``), the function must return an array having the smallest data type (in terms of range of values) capable of precisely representing the elements of ``x`` (e.g., if ``x`` is ``int16`` and the data type kind is ``'complex floating'``, then the returned array must have the data type ``complex64``; if ``x`` is `bool`` and the data type kind is ``integral``, then the returned array must have the data type ``int8``).