|
| 1 | +# Set Functions |
| 2 | + |
| 3 | +> Array API specification for creating and operating on sets. |
| 4 | +
|
| 5 | +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. |
| 6 | + |
| 7 | +- 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. |
| 8 | +- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. |
| 9 | +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. |
| 10 | + |
| 11 | +<!-- NOTE: please keep the functions in alphabetical order --> |
| 12 | + |
| 13 | +### <a name="unique" href="#unique">#</a> unique(x, /, *, return_counts=False, return_index=False, return_inverse=False, sorted=True) |
| 14 | + |
| 15 | +Returns the unique elements of an input array `x`. |
| 16 | + |
| 17 | +#### Parameters |
| 18 | + |
| 19 | +- **x**: _<array>_ |
| 20 | + |
| 21 | + - input array. If `x` has more than one dimension, the function must flatten `x` and return the unique elements of the flattened array. |
| 22 | + |
| 23 | +- **return_counts**: _bool_ |
| 24 | + |
| 25 | + - If `True`, the function must also return the number of times each unique element occurs in `x`. Default: `False`. |
| 26 | + |
| 27 | +- **return_index**: _bool_ |
| 28 | + |
| 29 | + - If `True`, the function must also return the indices (first occurrences) of `x` that result in the unique array. Default: `False`. |
| 30 | + |
| 31 | +- **return_inverse**: _bool_ |
| 32 | + |
| 33 | + - If `True`, the function must also return the indices of the unique array that reconstruct `x`. Default: `False`. |
| 34 | + |
| 35 | +- **sorted**: _bool_ |
| 36 | + |
| 37 | + - If `True`, the function must sort the unique elements in ascending order before returning as output. If `False`, the function must sort the unique elements in the same order that they occur in `x`. Default: `False`. |
| 38 | + |
| 39 | + _TODO: sort order needs discussion. See [gh-40](https://github.com/data-apis/array-api/issues/40)_ |
| 40 | + |
| 41 | +#### Returns |
| 42 | + |
| 43 | +- **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ |
| 44 | + |
| 45 | + - if `return_counts`, `return_index`, and `return_inverse` are all `False`, an array containing the set of unique elements in `x`; otherwise, a tuple containing two or more of the following arrays (in order): |
| 46 | + |
| 47 | + - **unique**: _<array>_ |
| 48 | + |
| 49 | + - an array containing the set of unique elements in `x`. |
| 50 | + |
| 51 | + - **indices**: _<array>_ |
| 52 | + |
| 53 | + - an array containing the indices (first occurrences) of `x` that result in `unique`. |
| 54 | + |
| 55 | + - **inverse**: _<array>_ |
| 56 | + |
| 57 | + - an array containing the indices of `unique` that reconstruct `x`. |
| 58 | + |
| 59 | + - **counts**: _<array>_ |
| 60 | + |
| 61 | + - an array containing the number of times each unique element occurs in `x`. |
0 commit comments