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 v be an element of x2 given by v = x2[j], where j refers to a valid index (see Indexing).

    • If v is less than all elements in x1, then out[j] must be 0.

    • If v is greater than all elements in x1, then out[j] must be M, where M is the number of elements in x1.

    • Otherwise, each returned index i = out[j] must satisfy an index condition:

      • If side == 'left', then x1[i-1] < v <= x1[i].

      • If side == 'right', then x1[i-1] <= v < x1[i].

    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.

Changed in version 2024.12: Fixed incorrect boundary conditions.