Python heapq.heapreplace() Method

heapq.heapreplace() function removes and returns the smallest element from a heap and inserts a new element into the heap in a single operation. This is useful when you need to replace the smallest item while maintaining the heap property.

Example: The following example replaces the smallest element in a heap with a new value.

import heapq

h = [3, 5, 7, 10]
heapq.heapify(h)
removed = heapq.heapreplace(h, 4)

print(removed)
print(h)

3
[4, 5, 7, 10]

Explanation: heapq.heapreplace(h, 4) removes the smallest element (3), inserts 4, and rearranges the heap to maintain the heap property.

Syntax

heapq.heapreplace(heap, item)

Parameters:

• heap: The heap list from which the smallest element will be replaced.
• item: The new value to insert into the heap.

Return Value: Returns the smallest element that was removed from the heap.

Working of heapq.heapreplace()

heapq.heapreplace() combines two operations into one:

• Removes and returns the smallest element from the heap.
• Inserts the new element into the heap.
• Rearranges the heap to maintain the heap property.

This operation is more efficient than calling heappop() and heappush() separately.

Examples

Example 1: This example removes the smallest element from the heap and replaces it with a new value. The heap is updated automatically after the operation.

import heapq

h = [2, 6, 8, 12]
heapq.heapify(h)

v = heapq.heapreplace(h, 5)
print(v)
print(h)

2
[5, 6, 8, 12]

Explanation: heapq.heapreplace(h, 5) removes the smallest value (2) and inserts 5 while keeping h as a valid heap.

Example 2: This example keeps only the top 3 largest scores by replacing the smallest score whenever a better score arrives.

import heapq

h = [50, 60, 70]
heapq.heapify(h)
new_score = 65

if new_score > h[0]:
    heapq.heapreplace(h, new_score)

print(h)

[60, 65, 70]

Explanation: heapq.heapreplace(h, new_score) replaces the smallest score (50) with 65, allowing the heap to keep only the top 3 scores.

Example 3: This example updates the highest-priority task by replacing the current smallest-priority entry with a new one.

import heapq

pq = [(1, "Task A"), (3, "Task C"), (2, "Task B")]
heapq.heapify(pq)

removed = heapq.heapreplace(pq, (0, "Urgent Task"))
print(removed)
print(pq)

(1, 'Task A')
[(0, 'Urgent Task'), (3, 'Task C'), (2, 'Task B')]

Explanation: heapq.heapreplace(pq, (0, "Urgent Task")) removes the current smallest-priority item and inserts the new task with priority 0.

When to Use heapq.heapreplace()

Use heapq.heapreplace() when:

• You want to replace the smallest element in a heap with a new value.
• You are maintaining a fixed-size heap.
• You need better performance than performing separate pop and push operations.

Comparison with Other Heap Methods

heapreplace() vs heappop() + heappush()

Both operations replace the smallest element, but heapreplace() performs the replacement in a single step and is more efficient.

smallest = heapq.heappop(heap)
heapq.heappush(heap, item)

The above code performs two heap operations, whereas heapreplace() does the same task in one operation.

heapreplace() vs heappushpop()

• heapreplace(heap, item) always removes the smallest element first and then inserts item.
• heappushpop(heap, item) inserts item first and then removes the smallest element.

If item is smaller than the current smallest element, heappushpop() may immediately return item, while heapreplace() always replaces an existing heap element.