From 8c414d644da1e88427948e0a14bce376670a8c9c Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 17 Feb 2021 00:03:25 -0500 Subject: [PATCH 1/4] add finfo and iinfo in the spec --- spec/API_specification/data_type_functions.md | 63 +++++++++++++++++++ spec/API_specification/index.rst | 1 + 2 files changed, 64 insertions(+) create mode 100644 spec/API_specification/data_type_functions.md diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md new file mode 100644 index 000000000..db4e19ce1 --- /dev/null +++ b/spec/API_specification/data_type_functions.md @@ -0,0 +1,63 @@ +# 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 + +(finfo)= +### finfo(type) + +Defines the machine limits for floating point types. + +#### Parameters + +- **type**: _Union\[ float, <dtype>, instance ]_ + + - the kind of floating point data-type about which to get information + +#### Returns + +- **out**: _<class>_ + + - a class with that encapsules the following attributes: + + - **bits**: _int_ + - The number of bits occupied by the type + - **eps**: _float_ + - The difference between 1.0 and the next smallest representable float larger than 1.0 following the IEEE 754 standard. + - **max**: _float_ + - The largest representable number. + - **min**: _float_ + - The smallest representable number. + - **tiny**: _float_ + - The smallest positive representable number. + - **resolution**: _float_ + - The approximate decimal resolution of this type. + +(iinfo)= +### iinfo(type) + +Defines the machine limits for integer types. + +#### Parameters + +- **type**: _Union\[ integer, <dtype>, instance ]_ + + - the kind of integer data-type about which to get information + +#### Returns + +- **out**: _<class>_ + + - a class with that encapsules the following attributes: + + - **bits**: _int_ + - The number of bits occupied by the type + - **max**: _int_ + - The largest representable number. + - **min**: _int_ + - The smallest representable number. diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 3d38b9c6b..55faa1c4d 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -11,6 +11,7 @@ API specification array_object indexing data_types + data_type_functions type_promotion broadcasting creation_functions From 39a9cb27c9ad98d174a1227d24127bdc69abdc95 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Wed, 17 Feb 2021 14:45:12 -0500 Subject: [PATCH 2/4] move result_type function to new file and minor fixes --- spec/API_specification/data_type_functions.md | 29 ++++++++++++++++--- spec/API_specification/utility_functions.md | 24 --------------- 2 files changed, 25 insertions(+), 28 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index db4e19ce1..689087185 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -15,7 +15,7 @@ Defines the machine limits for floating point types. #### Parameters -- **type**: _Union\[ float, <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, instance ]_ - the kind of floating point data-type about which to get information @@ -35,8 +35,6 @@ Defines the machine limits for floating point types. - The smallest representable number. - **tiny**: _float_ - The smallest positive representable number. - - **resolution**: _float_ - - The approximate decimal resolution of this type. (iinfo)= ### iinfo(type) @@ -45,7 +43,7 @@ Defines the machine limits for integer types. #### Parameters -- **type**: _Union\[ integer, <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, instance ]_ - the kind of integer data-type about which to get information @@ -61,3 +59,26 @@ Defines the machine limits for integer types. - The largest representable number. - **min**: _int_ - The 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 mixed dtypes (e.g. integer and floating-point) are used, the output of +`result_type` will be implementation-specific. +``` + +#### Parameters + +- **arrays_and_dtypes**: _Sequence\[Union\[<array>, <dtype>\]\];_ + + - input arrays and dtypes. + +#### Returns + +- **out**: _<dtype>_ + + - the dtype resulting from an operation involving the input arrays and dtypes. diff --git a/spec/API_specification/utility_functions.md b/spec/API_specification/utility_functions.md index a81b709ca..aad65a71b 100644 --- a/spec/API_specification/utility_functions.md +++ b/spec/API_specification/utility_functions.md @@ -64,27 +64,3 @@ Tests whether any input array element evaluates to `True` along a specified axis - **out**: _<array>_ - if a logical OR reduction was performed over the entire array, the returned array must be a zero-dimensional array containing the test result; otherwise, the returned array must be a non-zero-dimensional array containing the test results. The returned array must have a data type of `bool`. - - -(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 mixed dtypes (e.g. integer and floating-point) are used, the output of -`result_type` will be implementation-specific. -``` - -#### Parameters - -- **arrays_and_dtypes**: _Sequence\[Union\[<array>, <dtype>\]\];_ - - - input arrays and dtypes. - -#### Returns - -- **out**: _<dtype>_ - - - the dtype resulting from an operation involving the input arrays and dtypes. From 79dc82c176b1c040f3528d3d66b21c203846555f Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 18 Feb 2021 14:47:34 -0500 Subject: [PATCH 3/4] add review changes and remove tiny from the finfo object --- spec/API_specification/data_type_functions.md | 35 +++++++++---------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 689087185..30e541af6 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -11,41 +11,39 @@ A conforming implementation of the array API standard must provide and support t (finfo)= ### finfo(type) -Defines the machine limits for floating point types. +Machine limits for floating-point data types. #### Parameters -- **type**: _Union\[ <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, <array> ]_ - - the kind of floating point data-type about which to get information + - the kind of floating-point data-type about which to get information. #### Returns - **out**: _<class>_ - - a class with that encapsules the following attributes: + - an object having the following attributes: - **bits**: _int_ - - The number of bits occupied by the type + - number of bits occupied by the floating-point data type. - **eps**: _float_ - - The difference between 1.0 and the next smallest representable float larger than 1.0 following the IEEE 754 standard. + - difference between 1.0 and the next smallest representable floating-point number larger than 1.0 according to the IEEE-754 standard. - **max**: _float_ - - The largest representable number. + - largest representable number. - **min**: _float_ - - The smallest representable number. - - **tiny**: _float_ - - The smallest positive representable number. + - smallest representable number. (iinfo)= ### iinfo(type) -Defines the machine limits for integer types. +Machine limits for integer data types. #### Parameters -- **type**: _Union\[ <dtype>, instance ]_ +- **type**: _Union\[ <dtype>, <array> ]_ - - the kind of integer data-type about which to get information + - the kind of integer data-type about which to get information. #### Returns @@ -54,11 +52,11 @@ Defines the machine limits for integer types. - a class with that encapsules the following attributes: - **bits**: _int_ - - The number of bits occupied by the type + - number of bits occupied by the type - **max**: _int_ - - The largest representable number. + - largest representable number. - **min**: _int_ - - The smallest representable number. + - smallest representable number. (function-result_type)= ### result_type(*arrays_and_dtypes) @@ -67,13 +65,12 @@ Returns the dtype that results from applying the type promotion rules (see {ref}`type-promotion`) to the arguments. ```{note} -If mixed dtypes (e.g. integer and floating-point) are used, the output of -`result_type` will be implementation-specific. +If provided mixed dtypes (e.g., integer and floating-point), the returned dtype will be implementation-specific. ``` #### Parameters -- **arrays_and_dtypes**: _Sequence\[Union\[<array>, <dtype>\]\];_ +- **arrays_and_dtypes**: _Sequence\[ Union\[ <array>, <dtype> \] \];_ - input arrays and dtypes. From 2cc6683ed4205f3bdde2a5a0497d069dbc52f230 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 21 Feb 2021 16:29:48 +0100 Subject: [PATCH 4/4] Make finfo/info argument positional-only --- spec/API_specification/data_type_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/data_type_functions.md b/spec/API_specification/data_type_functions.md index 30e541af6..18269d2f1 100644 --- a/spec/API_specification/data_type_functions.md +++ b/spec/API_specification/data_type_functions.md @@ -9,7 +9,7 @@ A conforming implementation of the array API standard must provide and support t ## Objects in API (finfo)= -### finfo(type) +### finfo(type, /) Machine limits for floating-point data types. @@ -35,7 +35,7 @@ Machine limits for floating-point data types. - smallest representable number. (iinfo)= -### iinfo(type) +### iinfo(type, /) Machine limits for integer data types.