diff --git a/spec/API_specification/array_api/array_object.py b/spec/API_specification/array_api/array_object.py index 94dac2d1d..dd70a1beb 100644 --- a/spec/API_specification/array_api/array_object.py +++ b/spec/API_specification/array_api/array_object.py @@ -224,12 +224,22 @@ def __array_namespace__(self: array, /, *, api_version: Optional[str] = None) -> def __bool__(self: array, /) -> bool: """ - Converts a zero-dimensional boolean array to a Python ``bool`` object. + Converts a zero-dimensional array to a Python ``bool`` object. + + **Special cases** + + For real-valued floating-point operands, + + - If ``self`` is ``NaN``, the result is ``True``. + - If ``self`` is either ``+infinity`` or ``-infinity``, the result is ``True``. + - If ``self`` is either ``+0`` or ``-0``, the result is ``False``. + + For complex floating-point operands, special cases must be handled as if the operation is implemented as the logical AND of ``bool(real(self))`` and ``bool(imag(self))``. Parameters ---------- self: array - zero-dimensional array instance. Must have a boolean data type. + zero-dimensional array instance. Returns ------- @@ -237,6 +247,35 @@ def __bool__(self: array, /) -> bool: a Python ``bool`` object representing the single element of the array. """ + def __complex__(self: array, /) -> complex: + """ + Converts a zero-dimensional array to a Python ``complex`` object. + + **Special cases** + + For boolean operands, + + - If ``self`` is ``True``, the result is ``1+0j``. + - If ``self`` is ``False``, the result is ``0+0j``. + + For real-valued floating-point operands, + + - If ``self`` is ``NaN``, the result is ``NaN + NaN j``. + - If ``self`` is ``+infinity``, the result is ``+infinity + 0j``. + - If ``self`` is ``-infinity``, the result is ``-infinity + 0j``. + - If ``self`` is a finite number, the result is ``self + 0j``. + + Parameters + ---------- + self: array + zero-dimensional array instance. + + Returns + ------- + out: complex + a Python ``complex`` object representing the single element of the array instance. + """ + def __dlpack__(self: array, /, *, stream: Optional[Union[int, Any]] = None) -> PyCapsule: """ Exports the array for consumption by :func:`~array_api.from_dlpack` as a DLPack capsule. @@ -341,12 +380,22 @@ def __eq__(self: array, other: Union[int, float, bool, array], /) -> array: def __float__(self: array, /) -> float: """ - Converts a zero-dimensional floating-point array to a Python ``float`` object. + Converts a zero-dimensional array to a Python ``float`` object. + + .. note:: + Casting integer values outside the representable bounds of Python's float type is not specified and is implementation-dependent. + + **Special cases** + + For boolean operands, + + - If ``self`` is ``True``, the result is ``1``. + - If ``self`` is ``False``, the result is ``0``. Parameters ---------- self: array - zero-dimensional array instance. Must have a real-valued floating-point data type. + zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``. Returns ------- @@ -483,7 +532,7 @@ def __index__(self: array, /) -> int: Parameters ---------- self: array - zero-dimensional array instance. Must have an integer data type. + zero-dimensional array instance. Should have an integer data type. If ``self`` has a floating-point data type, the function must raise a ``TypeError``. Returns ------- @@ -493,17 +542,37 @@ def __index__(self: array, /) -> int: def __int__(self: array, /) -> int: """ - Converts a zero-dimensional integer array to a Python ``int`` object. + Converts a zero-dimensional array to a Python ``int`` object. + + **Special cases** + + For boolean operands, + + - If ``self`` is ``True``, the result is ``1``. + - If ``self`` is ``False``, the result is ``0``. + + For floating-point operands, + + - If ``self`` is a finite number, the result is the integer part of ``self``. + - If ``self`` is ``-0``, the result is ``0``. Parameters ---------- self: array - zero-dimensional array instance. Must have an integer data type. + zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``. Returns ------- out: int a Python ``int`` object representing the single element of the array instance. + + + **Raises** + + For floating-point operands, + + - If ``self`` is either ``+infinity`` or ``-infinity``, raise ``OverflowError``. + - If ``self`` is ``NaN``, raise ``ValueError``. """ def __invert__(self: array, /) -> array: diff --git a/spec/API_specification/array_object.rst b/spec/API_specification/array_object.rst index 758e08582..b45e41987 100644 --- a/spec/API_specification/array_object.rst +++ b/spec/API_specification/array_object.rst @@ -283,6 +283,7 @@ Methods array.__and__ array.__array_namespace__ array.__bool__ + array.__complex__ array.__dlpack__ array.__dlpack_device__ array.__eq__