From 528ecff87778f68f92c17cebb50b108a5bfb546e Mon Sep 17 00:00:00 2001 From: Willow Ahrens Date: Thu, 29 Oct 2026 12:14:15 -0400 Subject: [PATCH 1/2] add replace --- src/array_api_stubs/_draft/utility_functions.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/array_api_stubs/_draft/utility_functions.py b/src/array_api_stubs/_draft/utility_functions.py index 4ac290117..83050a084 100644 --- a/src/array_api_stubs/_draft/utility_functions.py +++ b/src/array_api_stubs/_draft/utility_functions.py @@ -119,3 +119,14 @@ def diff( .. versionadded:: 2024.12 """ + +def replace( + arr, + old, + new +): + """Return an array with every occurrence of scalar old replaced by new. + + Includes implicit sparse values and treats NaN as matching NaN. + The input is not modified. + """ \ No newline at end of file From 6181b2f89ed831e98b03684f3855fef0e705bb4d Mon Sep 17 00:00:00 2001 From: Willow Ahrens Date: Thu, 29 Oct 2026 12:19:55 -0400 Subject: [PATCH 2/2] fix --- .../API_specification/utility_functions.rst | 1 + .../_draft/utility_functions.py | 42 ++++++++++++++----- 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/spec/draft/API_specification/utility_functions.rst b/spec/draft/API_specification/utility_functions.rst index a09c99f79..e0a6f6942 100644 --- a/spec/draft/API_specification/utility_functions.rst +++ b/spec/draft/API_specification/utility_functions.rst @@ -21,3 +21,4 @@ Objects in API all any diff + replace diff --git a/src/array_api_stubs/_draft/utility_functions.py b/src/array_api_stubs/_draft/utility_functions.py index 83050a084..5b172dc37 100644 --- a/src/array_api_stubs/_draft/utility_functions.py +++ b/src/array_api_stubs/_draft/utility_functions.py @@ -1,4 +1,4 @@ -__all__ = ["all", "any", "diff"] +__all__ = ["all", "any", "diff", "replace"] from ._types import Optional, Tuple, Union, array @@ -120,13 +120,35 @@ def diff( .. versionadded:: 2024.12 """ + def replace( - arr, - old, - new -): - """Return an array with every occurrence of scalar old replaced by new. - - Includes implicit sparse values and treats NaN as matching NaN. - The input is not modified. - """ \ No newline at end of file + x: array, + old: Union[bool, int, float, complex], + new: Union[bool, int, float, complex], + /, +) -> array: + """ + Replaces each element of an input array ``x`` which is equal to a scalar value ``old`` with a scalar value ``new``. + + Parameters + ---------- + x: array + input array. + old: Union[bool, int, float, complex] + scalar value to replace. **Should** have a type and value compatible with the data type of ``x`` (see :ref:`mixing-scalars-and-arrays`). + new: Union[bool, int, float, complex] + replacement scalar value. **Should** have a type and value compatible with the data type of ``x`` (see :ref:`mixing-scalars-and-arrays`). + + Returns + ------- + out: array + an array in which each element ``x_i`` equal to ``old`` is replaced by ``new`` and all other elements are equal to the corresponding elements in ``x``. The returned array **must** have the same shape and data type as ``x``. + + Notes + ----- + + - An element ``x_i`` **must** be replaced if ``x_i`` is equal to ``old`` (see :func:`~array_api.equal`) or if both ``x_i`` and ``old`` are ``NaN`` (see :func:`~array_api.isnan`). + - The function **must** consider every element of ``x``, including elements which are not explicitly stored (e.g., implicit fill values in a sparse array representation). + - The function **must not** modify ``x``. + - If ``old`` or ``new`` does not have a type and value compatible with the data type of ``x``, behavior is unspecified and thus implementation-defined. + """