DOC: Add clarification about returned indices for np.searchsorted with sorter

[manodeep]

Issue with current documentation:

The documentation about the returned indices from np.searchsorted could be improved by clarifying that the returned indices refer to the sorter array and not the original (unsorted) array.

Now that I have manually confirmed that the indices do refer to sorter, I can also see that the searchsorted documentation contains this line - Find the indices into a sorted array a such that - but I failed to make that connection despite reading the documentation multiple times.

By adding something like "when sorter is present, then the returned indices refer to the sorter array (i.e., a[sorter[indices]] == v" (or equivalently, an example that shows the use of sorter and how the returned indices match the queried values). Even a pretend test code like the following would demonstrate the semantics for the return value for np.searchsorted when used with sorter.

from numpy.random import default_rng

rng = default_rng()
a_size = 30
a_max = 100
a = rng.choice(a_max, size=a_size, replace=False)
sorter = np.argsort(a)

find_size = 5
find_vals = np.random.choice(a, size=find_size)

idx = np.searchsorted(a, find_vals, sorter=sorter)

np.testing.assert_array_equal(find_vals, a[sorter[idx]])

(FIrst time opening an issue - apologies in advance if I am not correctly following some process)

Idea or request for content:

No response