8000 Add any/all specifications by kgryte · Pull Request #48 · data-apis/array-api · GitHub
[go: up one dir, main page]

Skip to content

Add any/all specifications #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 8, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions spec/API_specification/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,5 @@ API specification
linear_algebra_functions
searching_functions
set_functions
utility_functions
constants
62 changes: 62 additions & 0 deletions spec/API_specification/utility_functions.md
8000
Original file line number Diff line numberDiff line change
@@ -0,0 +1,62 @@
# Utility Functions

> Array API specification for utility functions.

A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.

- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.

<!-- NOTE: please keep the functions in alphabetical order -->

### <a name="all" href="#all">#</a> all(x, /, *, axis=None, keepdims=False)

Tests whether all input array elements evaluate to `True` along a specified axis.

#### Parameters

- **x**: _&lt;array&gt;_

- input array.

- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_

- axis or axes along which to perform a logical AND reduction. By default, a logical AND reduction must be performed over the entire array. If a tuple of integers, logical AND reductions must be performed over multiple axes. A valid `axis` must be an integer on the interval `[-N, N)`, where `N` is the rank (number of dimensions) of `x`. If an `axis` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If provided an invalid `axis`, the function must raise an exception. Default: `None`.

- **keepdims**: _bool_

- If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`.

#### Returns

- **out**: _&lt;array&gt;_

- if a logical AND reduction was performed over the entire array, a zero-dimensional array containing the test result; otherwise, a non-zero-dimensional array containing the test results. The returned array must be a boolean array (i.e., an array whose underlying data type is `bool`).

### <a name="any" href="#any">#</a> any(x, /, *, axis=None, keepdims=False)

Tests whether any input array element evaluates to `True` along a specified axis.

#### Parameters

- **x**: _&lt;array&gt;_

- input array.

- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_

- axis or axes along which to perform a logical OR reduction. By default, a logical OR reduction must be performed over the entire array. If a tuple of integers, logical OR reductions must be performed over multiple axes. A valid `axis` must be an integer on the interval `[-N, N)`, where `N` is the rank (number of dimensions) of `x`. If an `axis` is specified as a negative integer, the function must determine the axis along which to perform a reduction by counting backward from the last dimension (where `-1` refers to the last dimension). If provided an invalid `axis`, the function must raise an exception. Default: `None`.

- **keepdims**: _bool_

- If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`.

#### Returns

- **out**: _&lt;array&gt;_

- if a logical OR reduction was performed over the entire array, a zero-dimensional array containing the test result; otherwise, a non-zero-dimensional array containing the test results. The returned array must be a boolean array (i.e., an array whose underlying data type is `bool`).
0