diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md deleted file mode 100644 index 69a595b93..000000000 --- a/spec/API_specification/data_type_functions.md +++ /dev/null @@ -1,181 +0,0 @@ -# Data type functions - -> Array API specification for data type functions. - -A conforming implementation of the array API standard must provide and support the following data type functions. - - - -## Objects in API - -(function-astype)= -### astype(x, dtype, /, *, copy=True) - -Copies an array to a specified data type irrespective of {ref}`type-promotion` rules. - -```{note} -Casting floating-point `NaN` and `infinity` values to integral data types is not specified and is implementation-dependent. -``` - -```{note} -When casting a boolean input array to a numeric data type, a value of `True` must cast to a numeric value equal to `1`, and a value of `False` must cast to a numeric value equal to `0`. - -When casting a numeric input array to `bool`, a value of `0` must cast to `False`, and a non-zero value must cast to `True`. -``` - -#### Parameters - -- **x**: _<array>_ - - - array to cast. - -- **dtype**: _<dtype>_ - - - desired data type. - -- **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 must be returned. Default: `True`. - -#### Returns - -- **out**: _<array>_ - - - an array having the specified data type. The returned array must have the same shape as `x`. - -(function-broadcast_arrays)= -### broadcast_arrays(*arrays) - -Broadcasts one or more arrays against one another. - -#### Parameters - -- **arrays**: _<array>_ - - - an arbitrary number of to-be broadcasted arrays. - -#### Returns - -- **out**: _List\[ <array> ]_ - - - a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. - -(function-broadcast_to)= -### broadcast_to(x, /, shape) - -Broadcasts an array to a specified shape. - -#### Parameters - -- **x**: _<array>_ - - - array to broadcast. - -- **shape**: _Tuple\[int, ...]_ - - - array shape. Must be compatible with `x` (see {ref}`broadcasting`). - -#### Returns - -- **out**: _<array>_ - - - an array having a specified shape. Must have the same data type as `x`. - -#### Raises - -- if the array is incompatible with the specified shape (see {ref}`broadcasting`). - -(function-can_cast)= -### can_cast(from_, to, /) - -Determines if one data type can be cast to another data type according {ref}`type-promotion` rules. - -#### Parameters - -- **from_**: _Union\[ <dtype>, <array>]_ - - - input data type or array from which to cast. - -- **to**: _<dtype>_ - - - desired data type. - -#### Returns - -- **out**: _bool_ - - - `True` if the cast can occur according to {ref}`type-promotion` rules; otherwise, `False`. - -(function-finfo)= -### finfo(type, /) - -Machine limits for floating-point data types. - -#### Parameters - -- **type**: _Union\[ <dtype>, <array> ]_ - - - the kind of floating-point data-type about which to get information. - -#### Returns - -- **out**: _<finfo object>_ - - - an object having the following attributes: - - - **bits**: _int_ - - number of bits occupied by the floating-point data type. - - **eps**: _float_ - - difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. - - **max**: _float_ - - largest representable number. - - **min**: _float_ - - smallest representable number. - - **smallest_normal**: _float_ - - smallest positive floating-point number with full precision. - -(function-iinfo)= -### iinfo(type, /) - -Machine limits for integer data types. - -#### Parameters - -- **type**: _Union\[ <dtype>, <array> ]_ - - - the kind of integer data-type about which to get information. - -#### Returns - -- **out**: _<iinfo object>_ - - - a class with that encapsules the following attributes: - - - **bits**: _int_ - - number of bits occupied by the type - - **max**: _int_ - - largest representable number. - - **min**: _int_ - - smallest representable number. - -(function-result_type)= -### result_type(*arrays_and_dtypes) - -Returns the dtype that results from applying the type promotion rules -(see {ref}`type-promotion`) to the arguments. - -```{note} -If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. -``` - -#### Parameters - -- **arrays_and_dtypes**: _Union\[ <array>, <dtype> \]_ - - - an arbitrary number of input arrays and/or dtypes. - -#### Returns - -- **out**: _<dtype>_ - - - the dtype resulting from an operation involving the input arrays and dtypes. diff --git a/spec/API_specification/data_type_functions.rst b/spec/API_specification/data_type_functions.rst new file mode 100644 index 000000000..4b35a297a --- /dev/null +++ b/spec/API_specification/data_type_functions.rst @@ -0,0 +1,27 @@ +Data Type Functions +=================== + + Array API specification for data type functions. + +A conforming implementation of the array API standard must provide and support the following data type functions. + + +Objects in API +-------------- + +.. currentmodule:: signatures.data_type_functions + +.. + NOTE: please keep the functions in alphabetical order + +.. autosummary:: + :toctree: generated + :template: method.rst + + astype + broadcast_arrays + broadcast_to + can_cast + finfo + iinfo + result_type diff --git a/spec/API_specification/signatures/creation_functions.py b/spec/API_specification/signatures/creation_functions.py index aa25a24a2..0cb199850 100644 --- a/spec/API_specification/signatures/creation_functions.py +++ b/spec/API_specification/signatures/creation_functions.py @@ -54,7 +54,7 @@ def asarray(obj: Union[array, bool, int, float, NestedSequence, SupportsBufferPr .. admonition:: Note :class: note - If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :ref:`function-astype`. + If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :func:`signatures.data_type_functions.astype`. device: Optional[device] device on which to place the created array. If ``device`` is ``None`` and ``x`` is an array, the output array device must be inferred from ``x``. Default: ``None``. diff --git a/spec/API_specification/signatures/data_type_functions.py b/spec/API_specification/signatures/data_type_functions.py new file mode 100644 index 000000000..2356a8b2e --- /dev/null +++ b/spec/API_specification/signatures/data_type_functions.py @@ -0,0 +1,159 @@ +from ._types import List, Tuple, Union, array, dtype, finfo_object, iinfo_object + +def astype(x: array, dtype: dtype, /, *, copy: bool = True) -> array: + """ + Copies an array to a specified data type irrespective of :ref:`type-promotion` rules. + + .. note:: + Casting floating-point ``NaN`` and ``infinity`` values to integral data types is not specified and is implementation-dependent. + + .. note:: + When casting a boolean input array to a numeric data type, a value of ``True`` must cast to a numeric value equal to ``1``, and a value of ``False`` must cast to a numeric value equal to ``0``. + + When casting a numeric input array to ``bool``, a value of ``0`` must cast to ``False``, and a non-zero value must cast to ``True``. + + Parameters + ---------- + x: array + array to cast. + dtype: dtype + desired data type. + 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 must be returned. Default: ``True``. + + Returns + ------- + out: array + an array having the specified data type. The returned array must have the same shape as ``x``. + """ + +def broadcast_arrays(*arrays: array) -> List[array]: + """ + Broadcasts one or more arrays against one another. + + Parameters + ---------- + arrays: array + an arbitrary number of to-be broadcasted arrays. + + Returns + ------- + out: List[array] + a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array. + """ + +def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: + """ + Broadcasts an array to a specified shape. + + Parameters + ---------- + x: array + array to broadcast. + shape: Tuple[int, ...] + array shape. Must be compatible with ``x`` (see :ref:`broadcasting`). If the array is incompatible with the specified shape, the function should raise an exception. + + Returns + ------- + out: array + an array having a specified shape. Must have the same data type as ``x``. + """ + +def can_cast(from_: Union[dtype, array], to: dtype, /) -> bool: + """ + Determines if one data type can be cast to another data type according :ref:`type-promotion` rules. + + Parameters + ---------- + from_: Union[dtype, array] + input data type or array from which to cast. + to: dtype + desired data type. + + Returns + ------- + out: bool + ``True`` if the cast can occur according to :ref:`type-promotion` rules; otherwise, ``False``. + """ + +def finfo(type: Union[dtype, array], /) -> finfo_object: + """ + Machine limits for floating-point data types. + + Parameters + ---------- + type: Union[dtype, array] + the kind of floating-point data-type about which to get information. + + Returns + ------- + out: finfo object + an object having the followng attributes: + + - **bits**: *int* + + number of bits occupied by the floating-point data type. + + - **eps**: *float* + + difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. + + - **max**: *float* + + largest representable number. + + - **min**: *float* + + smallest representable number. + + - **smallest_normal**: *float* + + smallest positive floating-point number with full precision. + """ + +def iinfo(type: Union[dtype, array], /) -> iinfo_object: + """ + Machine limits for integer data types. + + Parameters + ---------- + type: Union[dtype, array] + the kind of integer data-type about which to get information. + + Returns + ------- + out: iinfo object + a class with that encapsules the following attributes: + + - **bits**: *int* + + number of bits occupied by the type. + + - **max**: *int* + + largest representable number. + + - **min**: *int* + + smallest representable number. + """ + +def result_type(*arrays_and_dtypes: Union[array, dtype]) -> dtype: + """ + Returns the dtype that results from applying the type promotion rules (see :ref:`type-promotion`) to the arguments. + + .. note:: + If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. + + Parameters + ---------- + arrays_and_dtypes: Union[array, dtype] + an arbitrary number of input arrays and/or dtypes. + + Returns + ------- + out: dtype + the dtype resulting from an operation involving the input arrays and dtypes. + """ + +__all__ = ['astype', 'broadcast_arrays', 'broadcast_to', 'can_cast', 'finfo', 'iinfo', 'result_type']