Add an example for sorter in dpnp.searchsorted docstrings

Author: antonwolfy

dpnp/dpnp_iface_searching.py

@@ -316,12 +316,14 @@ def searchsorted(a, v, side="left", sorter=None):
         If ``"left"``, the index of the first suitable location found is given.
         If ``"right"``, return the last such index. If there is no suitable
         index, return either 0 or N (where N is the length of `a`).
+
         Default: ``"left"``.
     sorter : {dpnp.ndarray, usm_ndarray}, optional
         Optional 1-D array of integer indices that sort array a into ascending
-        order. They are typically the result of :obj:`dpnp.argsort`.
+        order. They are typically the result of :py:func:`dpnp.argsort`.
         Out of bound index values of `sorter` array are treated using
         ``"wrap"`` mode documented in :py:func:`dpnp.take`.
+
         Default: ``None``.
 
     Returns
@@ -338,7 +340,7 @@ def searchsorted(a, v, side="left", sorter=None):
     Examples
     --------
     >>> import dpnp as np
-    >>> a = np.array([11,12,13,14,15])
+    >>> a = np.array([11, 12, 13, 14, 15])
     >>> np.searchsorted(a, 13)
     array(2)
     >>> np.searchsorted(a, 13, side='right')
@@ -347,6 +349,19 @@ def searchsorted(a, v, side="left", sorter=None):
     >>> np.searchsorted(a, v)
     array([0, 5, 1, 2])
 
+    When `sorter` is used, the returned indices refer to the sorted
+    array of `a` and not `a` itself:
+
+    >>> a = np.array([40, 10, 20, 30])
+    >>> sorter = np.argsort(a)
+    >>> sorter
+    array([1, 2, 3, 0])  # Indices that would sort the array 'a'
+    >>> result = np.searchsorted(a, 25, sorter=sorter)
+    >>> result
+    array(2)
+    >>> a[sorter[result]]
+    array(30)  # The element at index 2 of the sorted array is 30
+
     """
 
     usm_a = dpnp.get_usm_ndarray(a)