NumPy searchsorted()

Basic Usage of np.searchsorted()

The np.searchsorted() function returns the index where a value should be inserted in a sorted array to maintain the order. This is especially useful for search operations or inserting while keeping data sorted.

Example: Inserting Values in a Sorted Array

import numpy as np

arr = np.array([1, 3, 5, 7, 9])

# Find index to insert 4 to maintain order
idx = np.searchsorted(arr, 4)

print("Insert index for 4:", idx)

import numpy as np

arr = np.array([1, 3, 5, 7, 9])

# Find index to insert 4 to maintain order
idx = np.searchsorted(arr, 4)

print("Insert index for 4:", idx)

How It Works:

• searchsorted() assumes the input array is already sorted in ascending order.
• It performs a binary search to find the index where the input value should be inserted to maintain order.
• The default behavior inserts on the 'left' side of equal values (you can change this with the side parameter).
• The returned index tells you where to insert the new value, but it doesn't actually modify the array.

Output

Insert index for 4: 2

Insert index for 4: 2

💡 Tip: The array must be sorted. Otherwise, the result will be incorrect.

Using the side Parameter

The side parameter in np.searchsorted() controls which index is returned when the value being inserted already exists in the array. You can choose between:

• side='left' (default): Returns the first suitable index (inserts before equal values).
• side='right': Returns the last suitable index (inserts after equal values).

Example: Inserting with Different Sides

import numpy as np

arr = np.array([1, 3, 3, 5, 7])

# Default behavior (side='left')
left_idx = np.searchsorted(arr, 3, side='left')

# Insert after duplicates (side='right')
right_idx = np.searchsorted(arr, 3, side='right')

print("Insert index with side='left':", left_idx)
print("Insert index with side='right':", right_idx)

import numpy as np

arr = np.array([1, 3, 3, 5, 7])

# Default behavior (side='left')
left_idx = np.searchsorted(arr, 3, side='left')

# Insert after duplicates (side='right')
right_idx = np.searchsorted(arr, 3, side='right')

print("Insert index with side='left':", left_idx)
print("Insert index with side='right':", right_idx)

How It Works:

• side='left' returns the index before the first occurrence of the target value.
• side='right' returns the index after the last occurrence.
• This is useful when managing duplicates and deciding how new values should be positioned relative to them.

Output

Insert index with side='left': 1
Insert index with side='right': 3

Insert index with side='left': 1
Insert index with side='right': 3

💡 Tip: This is particularly useful when maintaining sorted arrays with duplicate entries, such as inserting events into a timeline or managing ranked data.

Inserting Multiple Values

np.searchsorted() can also handle an array of values to determine multiple insertion points in one call. This is useful for vectorized operations, such as placing several new values into a sorted array efficiently.

Example: Finding Insertion Indices for Multiple Values

import numpy as np

arr = np.array([10, 20, 30, 40])
values = np.array([25, 5, 35])

# Find insertion indices for each value
indices = np.searchsorted(arr, values)

print("Values to insert:", values)
print("Insertion indices:", indices)

import numpy as np

arr = np.array([10, 20, 30, 40])
values = np.array([25, 5, 35])

# Find insertion indices for each value
indices = np.searchsorted(arr, values)

print("Values to insert:", values)
print("Insertion indices:", indices)

How It Works:

• Each value in the input array is processed using binary search on the sorted array.
• The function returns an array of insertion indices, one for each input value.
• By default, it uses side='left' for duplicates, but you can change this just like with single values.

Output

Values to insert: [25  5 35]
Insertion indices: [2 0 3]

Values to insert: [25  5 35]
Insertion indices: [2 0 3]

💡 Tip: This behavior is fully vectorized — no need for a loop to find each index manually.

Inserting Values into the Array

While np.searchsorted() only returns the index where values should be inserted, you can use those indices with np.insert() to actually insert them into the array.

Example: Inserting a Value to Maintain Order

import numpy as np

arr = np.array([1, 3, 5, 7])
val = 4

# Get insertion index
idx = np.searchsorted(arr, val)

# Insert the value at the correct position
new_arr = np.insert(arr, idx, val)

print("Original array:", arr)
print("Value to insert:", val)
print("Insertion index:", idx)
print("New array:", new_arr)

import numpy as np

arr = np.array([1, 3, 5, 7])
val = 4

# Get insertion index
idx = np.searchsorted(arr, val)

# Insert the value at the correct position
new_arr = np.insert(arr, idx, val)

print("Original array:", arr)
print("Value to insert:", val)
print("Insertion index:", idx)
print("New array:", new_arr)

How It Works:

• np.searchsorted() determines the correct insertion point.
• np.insert() adds the value into the array at that index.
• The result is a new array; the original array remains unchanged unless reassigned.

Output

Original array: [1 3 5 7]
Value to insert: 4
Insertion index: 2
New array: [1 3 4 5 7]

Original array: [1 3 5 7]
Value to insert: 4
Insertion index: 2
New array: [1 3 4 5 7]

💡 Tip: This is useful when building or updating sorted arrays dynamically, such as inserting timestamps or ranked elements.

Frequently Asked Questions