pandas.Series.searchsorted — pandas 2.2.3 documentation (original) (raw)

Series.searchsorted(value, side='left', sorter=None)[source]#

Find indices where elements should be inserted to maintain order.

Find the indices into a sorted Series self such that, if the corresponding elements in value were inserted before the indices, the order of self would be preserved.

Note

The Series must be monotonically sorted, otherwise wrong locations will likely be returned. Pandas does _not_check this for you.

Parameters:

valuearray-like or scalar

Values to insert into self.

side{‘left’, ‘right’}, optional

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 self).

sorter1-D array-like, optional

Optional array of integer indices that sort self into ascending order. They are typically the result of np.argsort.

Returns:

int or array of int

A scalar or array of insertion points with the same shape as value.

Notes

Binary search is used to find the required insertion points.

Examples

ser = pd.Series([1, 2, 3]) ser 0 1 1 2 2 3 dtype: int64

ser.searchsorted(4) 3

ser.searchsorted([0, 4]) array([0, 3])

ser.searchsorted([1, 3], side='left') array([0, 2])

ser.searchsorted([1, 3], side='right') array([1, 3])

ser = pd.Series(pd.to_datetime(['3/11/2000', '3/12/2000', '3/13/2000'])) ser 0 2000-03-11 1 2000-03-12 2 2000-03-13 dtype: datetime64[ns]

ser.searchsorted('3/14/2000') 3

ser = pd.Categorical( ... ['apple', 'bread', 'bread', 'cheese', 'milk'], ordered=True ... ) ser ['apple', 'bread', 'bread', 'cheese', 'milk'] Categories (4, object): ['apple' < 'bread' < 'cheese' < 'milk']

ser.searchsorted('bread') 1

ser.searchsorted(['bread'], side='right') array([3])

If the values are not monotonically sorted, wrong locations may be returned:

ser = pd.Series([2, 1, 3]) ser 0 2 1 1 2 3 dtype: int64

ser.searchsorted(1)
0 # wrong result, correct would be 1