From 8a60b2e7c316f5af0e9902abebca079932a315ce Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 20:50:02 -0700 Subject: [PATCH 1/6] docs: move notes below the fold and highlight RFC 2119 keywords Ref: https://github.com/data-apis/array-api/issues/397 --- src/array_api_stubs/_draft/set_functions.py | 122 +++++++++----------- 1 file changed, 57 insertions(+), 65 deletions(-) diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index 5b7e9a56c..fd689849f 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -11,40 +11,38 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: .. admonition:: Data-dependent output shape :class: important - The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. - - .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). - - As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. - - Each ``nan`` value and each complex floating-point value having a ``nan`` component should have a count of one, while the counts for signed zeros should be aggregated as a single count. + The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, et cetera) can find this function difficult to implement without knowing array values. Accordingly, such libraries **may** choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function **must** flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: Tuple[array, array, array, array] a namedtuple ``(values, indices, inverse_indices, counts)`` whose - - first element must have the field name ``values`` and must be a one-dimensional array containing the unique elements of ``x``. The array must have the same data type as ``x``. - - second element must have the field name ``indices`` and must be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array must have the same shape as ``values`` and must have the default array index data type. - - third element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct ``x``. The array must have the same shape as ``x`` and must have the default array index data type. - - fourth element must have the field name ``counts`` and must be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts must match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array must have same shape as ``values`` and must have the default array index data type. - - .. note:: - The order of unique elements is not specified and may vary between implementations. + - first element **must** have the field name ``values`` and **must** be a one-dimensional array containing the unique elements of ``x``. The array **must** have the same data type as ``x``. + - second element **must** have the field name ``indices`` and **must** be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array **must** have the same shape as ``values`` and **must** have the default array index data type. + - third element **must** have the field name ``inverse_indices`` and **must** be an array containing the indices of ``values`` that reconstruct ``x``. The array **must** have the same shape as ``x`` and **must** have the default array index data type. + - fourth element **must** have the field name ``counts`` and **must** be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts **must** match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array **must** have same shape as ``values`` and **must** have the default array index data type. Notes ----- + - The order of unique elements by this function is not specified and **may** vary between implementations. + + - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + + - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + + As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. + + Each ``nan`` value and each complex floating-point value having a ``nan`` component **should** have a count of one, while the counts for signed zeros **should** be aggregated as a single count. + .. versionchanged:: 2022.12 Added complex data type support. @@ -60,36 +58,34 @@ def unique_counts(x: array, /) -> Tuple[array, array]: .. admonition:: Data-dependent output shape :class: important - The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. - - .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). - - Each ``nan`` value and each complex floating-point value having a ``nan`` component should have a count of one, while the counts for signed zeros should be aggregated as a single count. + The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) can find this function difficult to implement without knowing array values. Accordingly, such libraries **may** choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function **must** flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: Tuple[array, array] a namedtuple `(values, counts)` whose - - first element must have the field name ``values`` and must be a one-dimensional array containing the unique elements of ``x``. The array must have the same data type as ``x``. - - second element must have the field name `counts` and must be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts must match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array must have same shape as ``values`` and must have the default array index data type. - - .. note:: - The order of unique elements is not specified and may vary between implementations. + - first element **must** have the field name ``values`` and **must** be a one-dimensional array containing the unique elements of ``x``. The array **must** have the same data type as ``x``. + - second element **must** have the field name `counts` and **must** be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts **must** match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array **must** have same shape as ``values`` and **must** have the default array index data type. Notes ----- + - The order of unique elements returned by this function is not specified and **may** vary between implementations. + + - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + + - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + + Each ``nan`` value and each complex floating-point value having a ``nan`` component **should** have a count of one, while the counts for signed zeros **should** be aggregated as a single count. + .. versionchanged:: 2022.12 Added complex data type support. @@ -105,36 +101,34 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: .. admonition:: Data-dependent output shape :class: important - The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. - - .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). - - As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. + The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) can find this function difficult to implement without knowing array values. Accordingly, such libraries **may** choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function **must** flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: Tuple[array, array] a namedtuple ``(values, inverse_indices)`` whose - - first element must have the field name ``values`` and must be a one-dimensional array containing the unique elements of ``x``. The array must have the same data type as ``x``. - - second element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct ``x``. The array must have the same shape as ``x`` and have the default array index data type. - - .. note:: - The order of unique elements is not specified and may vary between implementations. + - first element **must** have the field name ``values`` and **must** be a one-dimensional array containing the unique elements of ``x``. The array **must** have the same data type as ``x``. + - second element **must** have the field name ``inverse_indices`` and **must** be an array containing the indices of ``values`` that reconstruct ``x``. The array **must** have the same shape as ``x`` and have the default array index data type. Notes ----- + - The order of unique elements returned by this function is not specified and **may** vary between implementations. + + - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + + - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + + As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. + .. versionchanged:: 2022.12 Added complex data type support. @@ -150,31 +144,29 @@ def unique_values(x: array, /) -> array: .. admonition:: Data-dependent output shape :class: important - The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. - - .. note:: - Uniqueness should be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - - - As ``nan`` values compare as ``False``, ``nan`` values should be considered distinct. - - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components should be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return ``-0`` if ``-0`` occurs before ``+0``). + The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) can find this function difficult to implement without knowing array values. Accordingly, such libraries **may** choose to omit this function. See :ref:`data-dependent-output-shapes` section for more details. Parameters ---------- x: array - input array. If ``x`` has more than one dimension, the function must flatten ``x`` and return the unique elements of the flattened array. + input array. If ``x`` has more than one dimension, the function **must** flatten ``x`` and return the unique elements of the flattened array. Returns ------- out: array - a one-dimensional array containing the set of unique elements in ``x``. The returned array must have the same data type as ``x``. - - .. note:: - The order of unique elements is not specified and may vary between implementations. + a one-dimensional array containing the set of unique elements in ``x``. The returned array **must** have the same data type as ``x``. Notes ----- + - The order of unique elements returned by this function is not specified and **may** vary between implementations. + + - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. + + - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. + - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + .. versionchanged:: 2022.12 Added complex data type support. From 1d9dcdf03dee7563b20ee9bc956a12359cf53f9b Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 20:53:50 -0700 Subject: [PATCH 2/6] fix: use correct grammar --- src/array_api_stubs/_draft/set_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index fd689849f..4e2288f85 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -31,7 +31,7 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: Notes ----- - - The order of unique elements by this function is not specified and **may** vary between implementations. + - The order of unique elements returned by this function is not specified and **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. From d26ea839988c4fb890b6aecc4040331a47f5341c Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 20:55:53 -0700 Subject: [PATCH 3/6] docs: use consistent phrasing --- src/array_api_stubs/_draft/set_functions.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index 4e2288f85..f4796b875 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -31,7 +31,7 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: Notes ----- - - The order of unique elements returned by this function is not specified and **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. @@ -76,7 +76,7 @@ def unique_counts(x: array, /) -> Tuple[array, array]: Notes ----- - - The order of unique elements returned by this function is not specified and **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. @@ -119,7 +119,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: Notes ----- - - The order of unique elements returned by this function is not specified and **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. @@ -159,7 +159,7 @@ def unique_values(x: array, /) -> array: Notes ----- - - The order of unique elements returned by this function is not specified and **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. From ce7ac724fe4ea5e8e0a211007ed2da2ca8d02c64 Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 20:56:55 -0700 Subject: [PATCH 4/6] docs: fix grammar --- src/array_api_stubs/_draft/set_functions.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index f4796b875..56eab6da8 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -31,7 +31,7 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. @@ -76,7 +76,7 @@ def unique_counts(x: array, /) -> Tuple[array, array]: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. @@ -119,7 +119,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. @@ -159,7 +159,7 @@ def unique_values(x: array, /) -> array: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, the element order **may** vary between implementations. + - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. From 65cf9c7e5440a8c914a30441dbaa7b3b6f1a0d85 Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 20:58:14 -0700 Subject: [PATCH 5/6] docs: use proper formatting --- src/array_api_stubs/_draft/set_functions.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index 56eab6da8..b43a11319 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -37,7 +37,7 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. @@ -82,7 +82,7 @@ def unique_counts(x: array, /) -> Tuple[array, array]: - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). Each ``nan`` value and each complex floating-point value having a ``nan`` component **should** have a count of one, while the counts for signed zeros **should** be aggregated as a single count. @@ -125,7 +125,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. @@ -165,7 +165,7 @@ def unique_values(x: array, /) -> array: - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should** not be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). .. versionchanged:: 2022.12 Added complex data type support. From dfeef133b88e4e25b812f05909248a442dd15760 Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 8 Jun 2025 21:09:23 -0700 Subject: [PATCH 6/6] docs: update language --- src/array_api_stubs/_draft/set_functions.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index b43a11319..7fee77ecb 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -31,13 +31,13 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. + - The order of unique elements returned by this function is unspecified and thus implementation-defined. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-defined (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. @@ -76,13 +76,13 @@ def unique_counts(x: array, /) -> Tuple[array, array]: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. + - The order of unique elements returned by this function is unspecified and thus implementation-defined. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-defined (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). Each ``nan`` value and each complex floating-point value having a ``nan`` component **should** have a count of one, while the counts for signed zeros **should** be aggregated as a single count. @@ -119,13 +119,13 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. + - The order of unique elements returned by this function is unspecified and thus implementation-defined. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-defined (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). As signed zeros are not distinct, using ``inverse_indices`` to reconstruct the input array is not guaranteed to return an array having the exact same values. @@ -159,13 +159,13 @@ def unique_values(x: array, /) -> array: Notes ----- - - The order of unique elements returned by this function is left unspecified and thus implementation-dependent. As a consequence, element order **may** vary between implementations. + - The order of unique elements returned by this function is unspecified and thus implementation-defined. As a consequence, element order **may** vary between implementations. - Uniqueness **should** be determined based on value equality (see :func:`~array_api.equal`). For input arrays having floating-point data types, value-based equality implies the following behavior. - As ``nan`` values compare as ``False``, ``nan`` values **should** be considered distinct. - As complex floating-point values having at least one ``nan`` component compare as ``False``, complex floating-point values having ``nan`` components **should** be considered distinct. - - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-dependent (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). + - As ``-0`` and ``+0`` compare as ``True``, signed zeros **should not** be considered distinct, and the corresponding unique element **may** be implementation-defined (e.g., an implementation **may** choose to return ``-0`` if ``-0`` occurs before ``+0``). .. versionchanged:: 2022.12 Added complex data type support.