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``). pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy