searchsorted

searchsorted(x1: array, x2: array, /, *, side: Literal['left', 'right'] = 'left', sorter: array | None = None) → array

Finds the indices into x1 such that, if the corresponding elements in x2 were inserted before the indices, the order of x1, when sorted in ascending order, would be preserved.

Parameters:

  • x1 (array) – input array. Must be a one-dimensional array. Should have a real-valued data type. If sorter is None, must be sorted in ascending order; otherwise, sorter must be an array of indices that sort x1 in ascending order.

  • x2 (array) – array containing search values. Should have a real-valued data type.

  • side (Literal['left', 'right']) –

    argument controlling which index is returned if a value lands exactly on an edge.

    Let x be an array of rank N where v is an individual element given by v = x2[n,m,...,j].

    If side == 'left', then

    • each returned index i must satisfy the index condition x1[i-1] < v <= x1[i].

    • if no index satisfies the index condition, then the returned index for that element must be 0.

    Otherwise, if side == 'right', then

    • each returned index i must satisfy the index condition x1[i-1] <= v < x1[i].

    • if no index satisfies the index condition, then the returned index for that element must be N, where N is the number of elements in x1.

    Default: 'left'.

  • sorter (Optional[array]) – array of indices that sort x1 in ascending order. The array must have the same shape as x1 and have an integer data type. Default: None.

Returns:

out (array) – an array of indices with the same shape as x2. The returned array must have the default array index data type.

Notes

For real-valued floating-point arrays, the sort order of NaNs and signed zeros is unspecified and thus implementation-dependent. Accordingly, when a real-valued floating-point array contains NaNs and signed zeros, what constitutes ascending order may vary among specification-conforming array libraries.

While behavior for arrays containing NaNs and signed zeros is implementation-dependent, specification-conforming libraries should, however, ensure consistency with sort and argsort (i.e., if a value in x2 is inserted into x1 according to the corresponding index in the output array and sort is invoked on the resultant array, the sorted result should be an array in the same order).

New in version 2023.12.