diff --git a/src/ragged/common/__init__.py b/src/ragged/common/__init__.py index e94a79c..dd70242 100644 --- a/src/ragged/common/__init__.py +++ b/src/ragged/common/__init__.py @@ -29,6 +29,11 @@ ) from ._datatype import ( astype, + can_cast, + finfo, + iinfo, + isdtype, + result_type, ) from ._obj import array @@ -52,6 +57,11 @@ "zeros_like", # _datatype "astype", + "can_cast", + "finfo", + "iinfo", + "isdtype", + "result_type", # _obj "array", ] diff --git a/src/ragged/common/_datatype.py b/src/ragged/common/_datatype.py index 6dcaa84..2c7a2be 100644 --- a/src/ragged/common/_datatype.py +++ b/src/ragged/common/_datatype.py @@ -6,10 +6,12 @@ from __future__ import annotations +from dataclasses import dataclass + +import numpy as np + from ._obj import array -from ._typing import ( - Dtype, -) +from ._typing import Dtype def astype(x: array, dtype: Dtype, /, *, copy: bool = True) -> array: @@ -36,3 +38,185 @@ def astype(x: array, dtype: Dtype, /, *, copy: bool = True) -> array: assert dtype, "TODO" assert copy, "TODO" assert False, "TODO" + + +def can_cast(from_: Dtype | array, to: Dtype, /) -> bool: + """ + Determines if one data type can be cast to another data type according type + promotion rules. + + Args: + from: Input data type or array from which to cast. + to: Desired data type. + + Returns: + `True` if the cast can occur according to type promotion rules; + otherwise, `False`. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.can_cast.html + """ + + assert from_, "TODO" + assert to, "TODO" + assert False, "TODO" + + +@dataclass +class finfo_object: # pylint: disable=C0103 + """ + Output of `ragged.finfo` with the following attributes. + + - bits (int): number of bits occupied by the real-valued floating-point + data type. + - eps (float): difference between 1.0 and the next smallest representable + real-valued floating-point number larger than 1.0 according to the + IEEE-754 standard. + - max (float): largest representable real-valued number. + - min (float): smallest representable real-valued number. + - smallest_normal (float): smallest positive real-valued floating-point + number with full precision. + - dtype (np.dtype): real-valued floating-point data type. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.finfo.html + """ + + bits: int + eps: float + max: float + min: float + smallest_normal: float + dtype: np.dtype + + +def finfo(type: Dtype | array, /) -> finfo_object: # pylint: disable=W0622 + """ + Machine limits for floating-point data types. + + Args: + type: the kind of floating-point data-type about which to get + information. If complex, the information is about its component + data type. + + Returns: + An object having the following attributes: + + - bits (int): number of bits occupied by the real-valued floating-point + data type. + - eps (float): difference between 1.0 and the next smallest + representable real-valued floating-point number larger than 1.0 + according to the IEEE-754 standard. + - max (float): largest representable real-valued number. + - min (float): smallest representable real-valued number. + - smallest_normal (float): smallest positive real-valued floating-point + number with full precision. + - dtype (np.dtype): real-valued floating-point data type. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.finfo.html + """ + + assert type, "TODO" + assert False, "TODO" + + +@dataclass +class iinfo_object: # pylint: disable=C0103 + """ + Output of `ragged.iinfo` with the following attributes. + + - bits (int): number of bits occupied by the type. + - max (int): largest representable number. + - min (int): smallest representable number. + - dtype (np.dtype): integer data type. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.iinfo.html + """ + + bits: int + max: int + min: int + dtype: np.dtype + + +def iinfo(type: Dtype | array, /) -> iinfo_object: # pylint: disable=W0622 + """ + Machine limits for integer data types. + + Args: + type: The kind of integer data-type about which to get information. + + Returns: + An object having the following attributes: + + - bits (int): number of bits occupied by the type. + - max (int): largest representable number. + - min (int): smallest representable number. + - dtype (np.dtype): integer data type. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.iinfo.html + """ + + assert type, "TODO" + assert False, "TODO" + + +def isdtype(dtype: Dtype, kind: Dtype | str | tuple[Dtype | str, ...]) -> bool: + """ + Returns a boolean indicating whether a provided dtype is of a specified data type "kind". + + Args: + dtype: The input dtype. + kind: Data type kind. + If `kind` is a `dtype`, the function returns a boolean indicating + whether the input `dtype` is equal to the dtype specified by `kind`. + + If `kind` is a string, the function returns a boolean indicating + whether the input `dtype` is of a specified data type kind. The + following dtype 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"`). + + If `kind` is a tuple, the tuple specifies a union of dtypes and/or + kinds, and the function returns a boolean indicating whether the + input `dtype` is either equal to a specified dtype or belongs to at + least one specified data type kind. + + Returns: + Boolean indicating whether a provided dtype is of a specified data type + kind. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.isdtype.html + """ + + assert dtype, "TODO" + assert kind, "TODO" + assert False, "TODO" + + +def result_type(*arrays_and_dtypes: array | Dtype) -> Dtype: + """ + Returns the dtype that results from applying the type promotion rules to + the arguments. + + Args: + arrays_and_dtypes: An arbitrary number of input arrays and/or dtypes. + + Returns: + The dtype resulting from an operation involving the input arrays and dtypes. + + https://data-apis.org/array-api/latest/API_specification/generated/array_api.result_type.html + """ + + assert arrays_and_dtypes, "TODO" + assert False, "TODO" diff --git a/src/ragged/v202212/__init__.py b/src/ragged/v202212/__init__.py index 7e1ec84..a5c76a2 100644 --- a/src/ragged/v202212/__init__.py +++ b/src/ragged/v202212/__init__.py @@ -31,6 +31,11 @@ ) from ._datatype import ( astype, + can_cast, + finfo, + iinfo, + isdtype, + result_type, ) from ._obj import array @@ -54,6 +59,11 @@ "zeros_like", # _datatype "astype", + "can_cast", + "finfo", + "iinfo", + "isdtype", + "result_type", # _obj "array", ] diff --git a/src/ragged/v202212/_datatype.py b/src/ragged/v202212/_datatype.py index eff6f05..501d473 100644 --- a/src/ragged/v202212/_datatype.py +++ b/src/ragged/v202212/_datatype.py @@ -8,8 +8,18 @@ from ..common._datatype import ( astype, + can_cast, + finfo, + iinfo, + isdtype, + result_type, ) __all__ = [ "astype", + "can_cast", + "finfo", + "iinfo", + "isdtype", + "result_type", ]